Xero FAQs

Owned by Nelson Leong
Last updated: Sept 18, 2024 by Maria Harreguy
7 min read

Errors:

Reactivation of employees - Error exporting a Timesheet for a former Employee

The error from Xero might say Invalid EmployeeID
This scenario is where an existing Employee left the company and came back. The person is using the same user in Workbench but it has been setup as a new employee in Xero. This means that the ExternalID on this user in Workbench is outdated and does not match the new ID in Xero.

Solution:
Delete the externalID on the people table in Workbench. Then when exporting the Timesheet the ExternalID will be populated with the new Xero ID.

Payroll Calendar has a Start Date after the date of the Timesheet

This means that the timesheet is not valid because it is for a fortnight that predates the start date of the calendar it belongs to.

Often this means that the pay run for this fortnight has already been completed in Xero. Try reverting/deleting the last pay run and then try the export again.

This error message a message will show until the calendar is fixed: "Payroll Calendar '{calendarName}' has a Start Date ({calendarStartDate}) after the date of the Timesheet ({TimesheetDate})."

 

“Xero API error calling UpdateOrCreateManualJournals: <html><head><title>504 Gateway Time-out</title>/head><body><center><h1>504 Gateway Time-out</h1></center></body></html>“

Solution:
The keyword in this error message returned by the Xero API is Time-out. This means that Xero has replied with a time-out error, and Xero’s server is momentarily unavailable. We suggest that you wait a few minutes and try exporting again. Any time-out errors, regardless of the batch type can be solved by waiting and trying the export a few minutes later.

In some cases, if the batch is too large, the time out might be because Xero API is trying to process too much data in one export. In this case, most commonly with timesheets or payroll, make sure you re-batch the batch and include fewer employees in it by using Payroll Names or Timesheet groups to reduce the number of people included in it. If you have a Wages Payroll Name in use already, you can split that into Wages and Wages2, as an example. Payroll Names are assigned to each employee, and will then become available for selection on the Batch as filters.

“Customer 'xxxx' does not have a Xero ID.”

Solution:
Make sure the company has the same value in the Workbench Company AR Account field and in the Xero client Account# field. Once they are both the same (check for hidden extra spaces), you can try to export again.

  • AR Account is the AR linking code to the financial system, and is required for companies marked as a Client.

  • AP Account is the AP linking code to the financial system, and is required for companies marked as a Supplier.

“The TaxType code … does not exist or cannot be used for this type of transaction.”

Solution:
The Export Code on the relevant GST Type must be a valid Tax Type in Xero (see Tax Types in Xero Documentation). This happens when one of the invoice lines does not have a valid tax type.

Payroll Calendar 'Fortnightly Calendar' is not found in Xero or Start Date is not defined.
Payroll Calendar 'xxxxxxx' is not found in Xero or Start Date is not defined.

Solution:
Workbench searches by default for a Payroll Calendar with the default names that come with the Xero database: Fortnightly Calendar for a Fortnighly pay period.

Weekly Calendar for a weekly pay period.

If any custom Pay Calendar is created with different Calendar Name, this Calendar Name must be set on Workbench Working Week table, on the CalendarName column using Scaffold access. Otherwise an error will be returned by Xero: Payroll Calendar 'Fortnightly Calendar' is not found in Xero or Start Date is not defined.

 

Earnings Rate 7519f7b5-c712-47a0-9962-e3b319e51b32 does not exist or is not valid for timesheets.

Solution:
This error could come up for several different reasons:

  1. Same Earning Pay Item exists as Active and Inactive. When you inactivate a Pay Item make sure to chnage the name to something different if a new one will be create dwith the same name. Example: Ordinary Hours OLD for the inactive Earning rate and Ordinary Hours for the new one.
    To check inactive Earning Pay Items select the 'Show inactive items'. If you see a duplicate one → Activate it → Change name → Inactivate it again.

     

  2. The Earnings Pay Item configuration is not correct. Even if it is an allowance it “must be configured like this:
    Rate = Rate per Unit
    Type of units = Hours

     

  3. Typo or extra spaces: The names must match exactly. Sometimes to the human eye they look the same but there could be extra spaces or a typo. Copy the Earnings Name from Xero and paste on Workbench Parroll Code. DO NOT TYPE IT, to avoid errors.

 

An existing contact could not be found using the specified contact details. The contact name field is required to create a new contact.

Solution: This means that the Supplier in Workbench has an ExternalID populated, but the corresponding Contact can’t be found in the Xero Tennant the current export is going to. This happens either when invoices for this Supplier have previously been exported to another Xero Tennant, and connected to a Contact in that Tennant; or when a Contact is imported into Workbench, and then deleted and re-created in Xero, leading to the ExternalID stored in Workbench to be out of date.

To fix it: Clear the ExternalID value of the relevant Company/Supplier in Scaffold, then try again. The integration will then try to re-populate the ExternalID with the matching Contact from the Xero Tennant this export is going to.

Note: a Supplier in Workbench can only be connected to a Contact in 1 Xero Tennant.

 

Xero does not support negative AR Invoices

Solution:

Process these as AR Credits instead.
Some financial systems do not accept negative AR invoices, in these cases, the control parameter 'Batch Negative Claims as Credits' can be set to Yes, so any Negative AR invoice or Negative Claim is automatically batched as a Credit Note so it can be successfully exported. This will mean that on the Claims tab on the Contract, these negative invoices will be called Credits when batched in Credit Batches.

There is also a utility called ‘'wbUtilityRebatchNegativeInvoices’', which transfers any negative invoices from an AR Invoice batch (FROM Batch) into a credit batch (TO Batch). If the control parameter mentioned above is enabled, there shouldn’t be a need to use this utility.

Xero API minute rate limit error calling…

Xero has various limits on how many times Workbench can call the Xero API (both as a whole, and for each client). If this message is displayed when exporting, please wait for at most a few minutes, and try the export again.

The error message has been updated to include the following:

Please retry export after {RetryAfter} seconds.

Account must be valid.

Various causes:

  • GL Account on the line in Workbench is not recognized as valid in Xero.

    • Fix GL Code on Activity

  • The Cost Rate on the line is effectively 0 (i.e. Quantity / Line Cost < 0.0001)

    • Reduce Quantity (to 1?)

Questions:

How do you import a Contact in Xero that is a Supplier and a Client?

Answer:
The integration support a Contact in Xero being either a Supplier or a Client in Workbench, but not both.
If it is both in Xero, it will only be flagged as a Client in Workbench. The workaround solution is to manually flag the Company as a Supplier after it has been imported into Workbench, and manually populate the AP Account number.

How do I reactivate a former employee in Workbench and/or Zero?

This scenario is where an existing Employee left the company and came back. The person is using the same user in Workbench but it has been setup as a new employee in Xero. This means that the ExternalID on this user in Workbench is outdated and does not match the new ID in Xero.

Solution:
Delete the externalID on the people table in Workbench. Then when exporting the Timesheet the ExternalID will be populated with the new Xero ID.

How do I disconnect from Xero?

In order to disconnect from Xero, navigate to the Xero Integration V2 screen in Workbench and click Disconnect button. Note: Disconnect button is visible only when you're connected to Xero.

What doesn’t your integration do?

Workbench integration does not automatically configure GL Accounts, Payroll Calendars and other Xero Settings.  However we do validate Companies and GL codes to quickly identify a mismatch between Workbench and Xero.

How do I reconcile sales data synced to Xero?

Workbench creates invoices in Xero in "Authorized" status. How you reconcile in Xero will depend on how you've mapped your "GL account" in Activities screen. Please, talk to our consulting team for more info.

When and how does data sync occur? Is it manual, automatic, on login, in real-time. Are there any settings related to synchronizing?

The Sync process occurs automatically every 1 hour for data coming from Xero to Workbench. All data from Workbench to Xero has to be exported manually from Export Control screen. The GL Mapping has to be configured on Activities screen.

There is also a manual import that can be triggered with the IMPORT button on the Xero Integration screen, if you cannot wait fort he automated task to execute.

Why is my archived Company in Xero still active in Workbench?

If a company that has been synced to Workbench is archived in Xero, it has to be manualy flaged as inactive in Workbench, as this status is not synced. And the same if the company is removed from Archive in Xero, it needs to manually be made active in Workbench.

Attachments to be exported exceed 2Mb

Xero does not allow the import of attachment files greater than 2MB. Therefore, Workbench will display a number next to the Succeeded status to indicate that there is a warning that you might want to take a look at. The warning message will say: Attachment xxxx.xxx exceeds 2MB size limit. Meaning it will not be exported.
The export of AR/AP Invoices will not fail, rather the attachment will not be exported.

 

Primary Person on Contacts

The Primary Person on a Contact in Xero will be imported as a Person in Workbench and linked to the Company (Supplier or Client).
If the Primary Person is created later, after the Contact was created in Xero and synced to Workbench, the Primary Person will be synced on the next scheduled sync (hourly). A manual sync can be triggered from the Xero Integration screen as well.