If your completed Unleashed transactions are failing to export to Xero or if there have been any syncing issues for your Supplier and Customer records, use the Connection Log and Failed Exports pages to identify and fix common errors that can occur.
Check your configuration
When investigating issues with data syncs between Unleashed and Xero, first check:
Confirm settings under Integration > Integration Store > Xero > Configuration tab align with your requirements.
Check if automatic export triggers are active and enabled for the correct advanced settings.
Ensure both Unleashed and Xero user roles have the necessary permissions. For additional assistance, refer to the official documentation or contact support.
Review failed exports to Xero
There are two ways to review the errors that can occur when data fails to sync successfully between Xero and Unleashed:
Review the Xero integration's Connection Log for errors or timestamps indicating when disconnection events occurred.
Click on the View Failed Exports link at the bottom of your Unleashed page.
🤓 Tip: It's best practice to periodically review the Xero integration's Connection Log and Export Data tab and check that transactions have been exported successfully. Variances are easier to resolve when reviewed often!
Xero's Connection Log
Review the Connection Log tab in your Xero integration to investigate and resolve any issues that may have occurred whilst Unleashed attempted to export your transactions or sync your Suppliers and Customers with Xero.
From the main menu, navigate to Integration > Integration Store > Xero.
Select the Connection Log tab.
All sync updates from the previous 7 days will be listed in date order (newest first) in the grid below.
Filter the connection log's grid using the following filter options:
Log Level: Use the drop-down menu to filter the grid's log by type: All, Error, or Info.
Search: A free text field that will filter the log's details by the specific text entered.
View Failed Exports
When a transaction or record fails to export or sync with Xero, it will be highlighted in the blue "Xero Export Queue" banner that displays at the bottom of your Unleashed pages.
Click on the View Failed Exports link, available in the "Xero Export Queue" banner. You will be redirected to the Manage Xero Queue page, which will display:
Current Xero Queue: A list of exports currently attempting to export to Xero.
Failed Xero Exports: A list of transactions or records that have not suscessfully exported.
Current Xero Queue
If an export is displayed in the current Xero queue for an extended period of time, it may be stuck and unable to export successfully. You can resolve this as follows:
In the Manage Xero Queue page, on the export's row, select Dequeue.
The export will be moved to the Failed Xero Exports list.
Click Export on the export's row.
If there are multiple exports stuck in the current Xero queue, you can click Dequeue All to move them all to the Failed Xero Exports list at once.
Failed Xero Exports
Within the Failed Xero Exports grid, each listed item will display the following information:
Failed Export: The type of transaction or record.
Exported Item: The transaction's, customer's or supplier's reference number, e.g. the transaction's order number or the customer's name.
Export Error: An explanation of why the transaction or record failed to export successfully.
Action Required: An explanation of the steps needed to resolve the error.
Export: A clickable link that will attempt to export the item.
Delete: A clickable link that will remove the failed export from the queue.
You can also click the Export All or Delete All links to bulk export or remove items from the failed export list.
Resolve Xero integration errors
When working with Unleashed and Xero integration, you may occasionally encounter errors that prevent transactions or data from exporting correctly to Xero. Common troubleshooting steps to resolve issues efficiently have been described below.
Period lock date
A lock date in Xero can block exports for transactions dated before the set lock date.
Error message: "The document date cannot be before the period lock date, currently set at XX-XXX-20XX. The document date cannot be before the end of year lock date, currently set at XX-XX-20XX"
Cause: The date the transaction is attempting to export is after the End of Year Lock Date set in Xero.
Solution: You will need to refer back to your Xero account and unlock the End of Year Lock Date, then re-export from Unleashed.
This error cannot be resolved in Unleashed directly.
Rate limit exceeded
Error message example: Response status code does not indicate success: 500 (Internal Server Error)
Cause: The number of transactions or records attempting to export and sync with Xero has exceeded its daily rate limit of 5000 requests.
Solution: The daily rate limit is a limitation set by Xero's API and cannot be extended by Unleashed. To resolve, wait 24 hours until the daily limit has reset, and then re-attempt exporting them from Unleashed.
For more details on Xero's integration limits, see Xero Rate limits.
Account code invalid
Error message example:
Account Code XXX is not a valid Code for this document.
Account code or ID must be specified.
Causes:
The account has been archived or no longer exists in Xero.
Default accounts are not configured in Unleashed.
Solution:
n Xero, open the Chart of Accounts and confirm the accounts exist and are active. Restore archived accounts or create valid replacements if necessary.
In Unleashed, go to Integration > Integration Store > Xero > Configuration.
Set the following default accounts:
Default Sales Account
Default Cost of Goods Sold (COGS) Account
Default Stock on Hand Account
Save the configuration.
Select the failed journal and click Export .
If the default accounts have been set in your configuration page and the error persists, request an account remap with the Support team.
Export fails due to account code alignment
Unleashed requires mapped Xero accounts to match specific account types in Xero’s Chart of Accounts. For example, accounts must be of type Revenue, Direct Cost, or Current Asset.
Solution:
In Xero, verify that the accounts used for mapping are of the correct type: - Stock on Hand accounts must be set as Current Asset.
If the account type is incorrect or locked, either:
Change the account type to the correct one in Xero.
Select or create a new account in Xero, of the correct type.
In Unleashed, go to Integration > Integration Store > Xero > Configuration and update the Default Stock on Hand account to the valid Xero account.
Retry the export.
Account and Tax are invalid
Error message example: Account must be valid, Tax Rate must be valid.
Cause: One of the product lines, or the sum total value of the exporting journal transaction, is less than 0.005.
Solution: There is no fix for this error, as Xero is only able to import journals with a value of 0.01 or greater. Journals with a value of 0.005 or less are rounded to a value of 0.00 and therefore negligible to Xero's accounts. We therefore suggest deleting the error from your Failed Exports Queue.
Alternatively, if you have multiple lines of value on the same order that require exporting to Xero, credit the whole sales order and raise a new one. If you need to include the product which triggered the error, you would need to adjust its decimal value and/or discount it 100% if it is not something the customer pays for.
Please note: This workaround may not be suitable for all businesses.
Account Number already exists
Error message example: The Account Number already exists. Please enter a different Account Number.
Cause: The Customer Code already exists as an Account Number in Xero but the contact details don't match.
Solution:
Go to Integration > Xero > Configuration,
On Export Customers click Configure
Untick "Send Customer Code to Xero account number".
Click Save Configuration.
Alternatively, remove the Account Number from Xero's contact.
Unmapped accounting tax
Error message example: Export of XXX to Xero Invoices API failed - Details: [TaxCode XXX] is not mapped to an accounting tax.
Cause:
The Tax Code on the transaction is not mapped with a Tax set up in Xero.
The tax being used in the transaction is selected as both a Purchase and Sales tax.
The Customer record does not have Taxable enabled.
Solution:
Go to Settings > System > Taxes.
Confirm all taxes have an option selected in the "Accounting Tax" dropdown menu. If the field is empty and the appropriate tax isn't listed to select, create the tax in Xero.
Confirm all taxes only have either "Purchase" or "Sale" ticked. If the tax being used has both ticked, create a new tax for each transaction type.
Go to the Customer or Supplier's record and confirm the "taxable" setting is enabled.
If the transaction is already completed and the tax in use cannot be changed, contact the Support Team.
Xero validation error
Error message example: Export of XXX to Xero Contacts API failed - Details: Xero validation error.
Cause: The Customer or Supplier's GST or VAT Number is invalid.
Solution: Update the Customer or Supplier's GST or VAT Number in Unleashed and ensure it's in a valid format, matching the country specified in the contact's settings in Xero, then re-export from Unleashed.
Archived contact
Error message example: The specified contact details matched an archived contact. Archived contacts cannot currently be edited via the API.
Cause: The previously mapped contact in Xero has been deleted, merged or archived in Xero, disrupting it's sync with Unleashed.
Solution:
If the contact was archived in Xero, go to Xero's contact and un-archive it, then re-export from Unleashed to re-establish a successful mapping. For more details, see Archive or restore contacts.
If the contact was merged with another contact in Xero, obtain the merged contact's URL from Xero and request that the contact be re-mapped with the support team.
Contact email address is invalid
Error message example: API failed - Details: * Email address must be valid.
Cause: The email address for the Supplier or Customer contact is not given in a valid format in Unleashed.
Solution: Update the Supplier or Customer contact in Unleashed to ensure:
Only one email address is provided per contact.
No commas, spaces or additional characters are included in the email field, other than the email address.
The email address is in a valid format.
Duplicate contact name
If a customer’s details (e.g., name or email) match an archived contact in Xero, the export will fail due to conflicts.
Error message: "The contact name XXXX is already assigned to another contact. The contact name must be unique across all active contacts."
Cause: The email address for the contact already exists under another contact in Xero.
Solution: All mapped contacts from Unleashed must be unique across all contacts (both Suppliers and Customers) in Xero. To resolve the error:
Update the email address and name for the contact in Unleashed to ensure it's unique.
Remove the existing email address for the contact in Xero if it's no longer used for them.
Prevention tips:
Ensure new customer names in Unleashed are unique and do not match existing Xero contacts.
If overwriting occurs, manually update the contact details in Xero to restore the original information.
Duplicate bills in Xero
Duplicate bills in Xero often arise due to the following scenarios:
Manual edits in Xero: If a Purchase Order (PO) exported from Unleashed is edited in Xero (e.g., changing the PO number, prefix, or reference), Unleashed may no longer recognize the bill as the original export. When the PO is later completed in Unleashed, the integration exports it again, creating duplicate draft bills for the same deliveries and values.
Manual Bill creation in Xero: If a bill is manually created in Xero for a PO that has not yet been exported from Unleashed, and the PO is later exported, duplicates can occur.
Solution: If duplicate bills have already occurred in Xero:
Identify the Correct Bill: Confirm that the bill exported from Unleashed exists and matches the intended details.
Remove Manual Duplicates: Delete the manually created duplicates in Xero. This is typically the cleanest approach.
Add Notes for Clarity (Optional): Before deleting manual entries, consider adding a note explaining that they were temporary placeholders. This can help maintain accounting and reporting clarity.
Prevent Duplicate Bills
To avoid duplicate bills when using Unleashed with Xero, follow these best practices:
Avoid Editing Exported Data: Do not edit the PO number, prefix, or reference on bills in Xero until the related PO is fully completed in Unleashed. Make any required changes in Xero only after the PO has been completed, and no further exports are expected.
Avoid Manual Bill Creation: Do not manually create bills in Xero for POs or invoices that are already being generated in Unleashed, including those from eCommerce integrations.
Complete Processes in Unleashed First: Ensure that all POs or sales processes are finalized in Unleashed before making any changes in Xero.
Best Practices for Preventing Errors
Regularly Synchronize Contacts: Keep Unleashed and Xero contacts synchronized to avoid mapping issues.
Ensure Unique Contact Names: Avoid duplicate or similar names for customers and suppliers.
Monitor Archived Contacts: Periodically review and manage archived contacts in Xero.
Disable Automatic Customer Updates: If customer emails differ between Unleashed and Xero, ensure "Export customer contacts" is turned off to prevent unintended updates.