# Xero Integration in Scheduling Source: https://docs.astalty.com.au/guide/scheduling/xero-integration-in-scheduling > Set up the Xero integration so scheduling timesheet batches can be processed in Xero. Scheduling add-on - This feature requires the Scheduling add-on, which is available on Astalty Premium. See How to enable 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**](https://app.astalty.com.au/settings/integrations), find Xero, and select **Connect**. ![The Integrations settings page showing the Xero card, which describes the 2-way integration for invoices and payments, with the Connect button in the bottom right.](https://docs.astalty.com.au/assets/xero-card.png) ### Allow Access Log in to Xero if prompted, review the requested access, and allow Astalty to connect. ![The Xero access request page listing the organisation data and user account information Astalty wants to access, with the Allow access and Cancel buttons.](https://docs.astalty.com.au/assets/xero-access-request.png) If Xero Payroll is not yet configured, complete [Xero Configuration](#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. ![Xero Payroll settings on the Pay Frequencies tab, with an arrow to the highlighted Fortnightly Calendar row and the Add button at the top right of the list.](https://docs.astalty.com.au/assets/xero-sched-3.png) ### 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. ![Xero Payroll settings on the Pay Items tab, showing the Earnings list with each item's category, rate and account, and the Add button highlighted.](https://docs.astalty.com.au/assets/xero-sched-7.png) ![The Xero Ordinary Time Earnings dialog for a new pay item, with Earnings Name Night (Hours), Rate Type Rate per Unit, Type of Units Hours, Expense Account 477: Wages and Salaries, and the Add button.](https://docs.astalty.com.au/assets/xero-sched-24.png) ### Employees In Xero, open **Payroll > Employees**. These employees become available for mapping to Astalty users. Select **New employee** to add anyone who is missing. ![The Xero Payroll menu open with Employees highlighted under Employee Management, and the New employee button highlighted above the Employees list.](https://docs.astalty.com.au/assets/xero-sched-20.png) ### 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](https://docs.astalty.com.au/guide/setup-pay-items-and-employee-templates-in-xero). Check the resulting pay-run amounts before posting. ![The Xero Payroll menu, highlighted in the top bar, with an arrow pointing to Employees under Employee Management.](https://docs.astalty.com.au/assets/employees-1.png) ![The Xero Employees list with one employee's row highlighted, showing their email, Fortnightly Calendar pay frequency and next payment date.](https://docs.astalty.com.au/assets/employees-2.png) ![An employee's Pay Templates page in Xero with the Pay Template tab highlighted and an arrow pointing to the Add Earnings Line button.](https://docs.astalty.com.au/assets/employees-3a.png) ![The Xero Add an Earnings Line dialog with Earnings Rate set to Ordinary Hours and Calculation Type set to Enter Rate, both highlighted, and an arrow pointing to the OK button.](https://docs.astalty.com.au/assets/employees-4.png) ![An employee's Pay Template in Xero with an Ordinary Hours earnings line, its Rate field highlighted showing 34.580000, and an arrow pointing to the Save button.](https://docs.astalty.com.au/assets/employees-5.png) ## 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](https://app.astalty.com.au/settings/scheduling). ![Scheduling Settings in Astalty, reached from Settings (1) then General (2), with the Platform set to Xero highlighted in the Payroll and Awards section and an arrow pointing to its Edit button (3).](https://docs.astalty.com.au/assets/xero-sched-1.png) ![The Payroll and Awards drawer with the Platform dropdown open, listing Xero, Employment Hero, PayCat, QuickBooks Payroll and Other, and an arrow pointing to Xero.](https://docs.astalty.com.au/assets/xero-sched-2.png) Select **Update** to save your changes. ### Payroll Calendar Open the [**Xero Integration Overview**](https://app.astalty.com.au/settings/integrations/xero) in Astalty and select **Edit**. ![The Xero Integration Settings Overview in Astalty, showing the connected organisation Demo Company (AU), the default sales account, invoice and sync settings and the Fortnightly Calendar payroll calendar, with an arrow pointing to the highlighted Edit button.](https://docs.astalty.com.au/assets/xero-sched-5.png) Select the required **Payroll Calendar** (the Pay Frequency setup in Xero), and then **Update** to save your changes. ![The Payroll Calendar field in the Update Xero Integration Settings drawer, highlighted and open below the Default Staff Payment Account, listing Fortnightly Calendar and Weekly Calendar.](https://docs.astalty.com.au/assets/xero-sched-4.png) > **Which batches use this payroll calendar** > > Astalty checks this calendar only when a batch was created from a manual date range. A batch generated **By Xero payroll calendar** is checked against the calendar used to generate it. > > If you run more than one pay cycle, [sync the payroll calendars from Xero](https://docs.astalty.com.au/guide/sync-payroll-calendars-from-xero) and create a batch for each calendar. Here, select the calendar used by most Support Workers so manually dated batches use the most useful default. ### Pay Groups Pay Groups organise the Pay Items used for different workers and employment conditions. Open [**Xero Integration > Pay Groups**](https://app.astalty.com.au/settings/integrations/xero/pay-groups), then select **Add Pay Group** if you need one. ![The Pay Groups page in the Xero integration settings, with Pay Groups selected in the side menu, the list of Pay Groups (Administration and Support Worker) highlighted, and an arrow pointing to the highlighted Add Pay Group button.](https://docs.astalty.com.au/assets/xero-sched-6.png) 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](https://docs.astalty.com.au/guide/setup-pay-groups-and-employees-in-astalty). ![The Create Pay Group drawer with Casual Support Workers entered in the highlighted Pay Group Name field, the Award set to SCHADS Award, and an arrow pointing to the Create Pay Group button.](https://docs.astalty.com.au/assets/xero-sched-22.png) Use the **3 dot menu** of the Pay Group you just created to select **Edit Pay Item Mapping**. ![The Pay Groups list with the Support Worker pay group's 3 dot menu open and highlighted, and an arrow pointing to the highlighted Edit Pay Item Mapping option below Edit Pay Group.](https://docs.astalty.com.au/assets/xero-sched-23.png) Map each Astalty Pay Item to the matching Xero pay item or rate. If your workers use the [On-Call Roster](https://docs.astalty.com.au/guide/scheduling/on-call-roster), map its on-call rows too; see [Mapping On-Call Pay Items](https://docs.astalty.com.au/guide/scheduling/on-call-roster#mapping-on-call-pay-items). ![The Pay Item Mapping drawer for the Support Worker pay group, with the Pay rate selectors highlighted, mapping each Astalty Pay Item, such as Weekday Daytime, Weekday Afternoon, Weekday Night, Saturday, Sunday and Public Holiday, to a matching Xero pay rate.](https://docs.astalty.com.au/assets/xero-sched-9.png) Use a Pay Group's **3 dot menu** to select **Edit Pay Group** or **Edit Pay Item Mapping**. ![The Pay Groups list with the Support Worker pay group's 3 dot menu highlighted and open, showing the Edit Pay Group and Edit Pay Item Mapping options.](https://docs.astalty.com.au/assets/xero-sched-8.png) You can delete a Pay Group only when it is not assigned to any user. ### Employees Open [**Xero Integration > Employees**](https://app.astalty.com.au/settings/integrations/xero/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**. ![The Employees page in the Xero integration settings, with the Xero Employee is Not Linked filter highlighted and an arrow pointing to the Not Linked badges in the Linked column of the listed users.](https://docs.astalty.com.au/assets/xero-sched-11.png) Select the matching Xero employee, then select **Update**. ![The Update Payroll Platform Details drawer for Jack Brown with the Xero Employee dropdown open, listing Xero employees with their email addresses under a search box, and an arrow pointing into the list.](https://docs.astalty.com.au/assets/xero-sched-13.png) Linked users appear in the **Linked** list. Use **Link Xero Employee** on one to change the linked Xero employee. ![The Employees page in the Xero integration settings with the Xero Employee is Linked filter highlighted, and the Linked column highlighted showing every listed user as Linked.](https://docs.astalty.com.au/assets/xero-sched-10.png) #### Missing Employees If an employee is missing from the dropdown, add or finish setting them up as an employee in Xero. ![The Xero Employee dropdown open, showing a search box and the start of the list of Xero employees with their email addresses.](https://docs.astalty.com.au/assets/xero-sched-19.png) ![The Xero Payroll menu open, with an arrow from Payroll to the highlighted Employees option and another arrow to the highlighted New employee button.](https://docs.astalty.com.au/assets/xero-sched-21.png) If an employee cannot be found in either Linked or Not Linked, make sure the user has their own Astalty profile under [Users](https://app.astalty.com.au/users). ### Custom Allowances When [custom allowances](https://docs.astalty.com.au/guide/scheduling/setup/custom-allowances) are in use, open [**Xero Integration > Custom Allowances**](https://app.astalty.com.au/settings/integrations/xero/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](https://docs.astalty.com.au/guide/scheduling/setup/custom-allowances#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. ![The Create Timesheet Batch page with From and To dates, and a highlighted notice reading Your next Xero payroll period is from 26/10/2026 to 08/11/2026, with an Apply dates button.](https://docs.astalty.com.au/assets/xero-payroll-period-guide.png) Once you have generated your Timesheet Batch, use the **Actions** button to select **Export Xero Timesheet (API)**. See our [Timesheet Batches guide](https://docs.astalty.com.au/guide/scheduling/timesheet-batches) for more information on how to create these. ![A Timesheet Batch with the Actions menu open and the Export Xero Timesheet (API) option highlighted, between Export Timesheet as Excel and Delete.](https://docs.astalty.com.au/assets/xero-sched-14.png) When you're ready to sync the Timesheets batch with Xero, select **Validate**. ![A Timesheet Batch showing its Details and the things to check in the period, with the Export for Xero panel below and the Validate button highlighted.](https://docs.astalty.com.au/assets/xero-sched-15.png) After validation, answer the export questions, then select **Create Export**. ![The Export for Xero panel after validation, with Employees set to All Employees, two acknowledgement checkboxes ticked and highlighted, and an arrow pointing to the Create Export button.](https://docs.astalty.com.au/assets/xero-timesheet-sync.png) After selecting **Create Export**, review the new entry under **Export Results**. A successful sync reaches **Completed**. ![The Timesheet Batch Export Results panel with the export's Status highlighted as Completed.](https://docs.astalty.com.au/assets/xero-timesheet-sync-2.png) > **Export "Completed"** > > You can start another export after the previous export reaches **Completed** or **Failed**. A **Queued** or **Processing** export must finish first. Do not resend employees whose timesheets already succeeded: select only employees still needing export, or first delete their existing draft through **Actions > Manage Xero Timesheets**. Xero accepts only one timesheet per employee for a pay period, and Astalty can delete only **Draft** timesheets. See [Managing Xero Draft Timesheets](https://docs.astalty.com.au/guide/scheduling/timesheet-batches#managing-xero-draft-timesheets). Synced timesheets appear in Xero with a status of **Draft**, ready for processing. ![The Xero Timesheets list with several timesheets for the fortnight ending 28 Nov 2025 highlighted, each with the status Draft.](https://docs.astalty.com.au/assets/xero-sched-17.png) ## 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](https://docs.astalty.com.au/guide/scheduling/timesheet-batches#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. > **What the Why this export failed drawer gives you** > > For each rejection, the drawer explains the cause, shows Xero's exact message, and links to the relevant screen and troubleshooting instructions. > > If Astalty doesn't recognise the specific rejection, the drawer still opens but shows Xero's message with a general **Read the guide** link - contact support with that message if you're unsure what it means. Older failures that weren't captured in detail have no **Fix issue** button at all; the reason is shown in the panel instead. ### 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. ![The Export Results panel with a Failed export whose reason says Xero already has a timesheet for Priya Nair in this pay period, and the Fix issue button highlighted.](https://docs.astalty.com.au/assets/xero-timesheet-export-results-fix-issue-guide.png) 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](https://docs.astalty.com.au/guide/scheduling/timesheet-batches#managing-xero-draft-timesheets) 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. > **A pay run blocks the batch dates as well as the timesheet** > > A pay run for the period moves Xero's next payroll period past the batch, so **Validate** fails on the batch dates until the pay run is deleted - see [Incorrect Timesheet Batch Dates](#incorrect-timesheet-batch-dates). > **Not every clashing timesheet appears in Manage Xero timesheets** > > **Manage Xero timesheets** lists only the drafts Astalty can see. Timesheets that are approved, awaiting approval, rejected or processed won't be there, and neither will a draft the worker entered in Xero Me - Xero hides those from payroll admins and won't let Astalty delete them. ### 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. ![The Export for Xero panel with a red validation error stating the timesheet batch dates (19-10-2026 to 25-10-2026) do not match the Xero next payroll period (12-10-2026 to 25-10-2026).](https://docs.astalty.com.au/assets/xero-sched-27.png) #### 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. 1. In Xero, open the pay run covering the batch period. If it's posted, revert it to draft. 2. Delete the pay run. 3. If a timesheet for the period is still in Xero, remove it - see [Timesheet Already Exists](#timesheet-already-exists). 4. In Astalty, select **Validate** and run the export again. 5. Create the pay run again in Xero. > **Reverting a pay run to draft isn't enough on its own** > > Only deleting a pay run rolls the payroll calendar's start date back. Posting and reverting don't move it, so reverting to draft unlocks the timesheet the pay run was holding but leaves the batch dates blocked. > > Don't delete a pay run you've already filed with the ATO and paid. Add the hours in Xero instead, or export the batch as a file and enter it there. #### 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](https://docs.astalty.com.au/guide/scheduling/timesheet-batches#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. ![The Export for Xero panel with highlighted errors: the batch dates do not match the next Xero payroll period, and Sally Jones and Jack Brown are listed with the error User is missing a Xero Employee ID.](https://docs.astalty.com.au/assets/xero-sched-25-guide.png) 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. ![The Export for Xero error list of users missing a Xero Employee ID, with the Fix issue button on each row highlighted.](https://docs.astalty.com.au/assets/xero-sched-26-guide.png) ### 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. ![The Export for Xero panel on a Timesheet Batch with a highlighted error listing Margaret Fielding, who does not have an employment contract within the timesheet batch period, and the Validate button below.](https://docs.astalty.com.au/assets/no-employment-contract.png) ## Xero Pay Item Configuration Walk-Through Set up your pay items before linking Astalty and Xero. Use the [Xero Payroll - Pay Item Configuration](https://docs.google.com/spreadsheets/d/1aYA3zmdC9kLpz-91gbSQi7hAR_0sZ04IGpcMyPQM7DE/edit?gid=1275525005#gid=1275525005) reference for the required pay items and the video walkthrough for creating them in Xero. Video walkthrough: xero pay items. ## Xero Payroll Integration Walk-Through This recording covers payroll setup in Xero and Astalty, including employee settings, pay items, and pay rates. Video walkthrough: xero payroll integration walk through.