Common Xero Export Errors
This troubleshooting guide provides solutions to common errors encountered when using the HirePOS Xero exporter. If you are facing issues with the Xero integration, refer to the sections below for guidance on resolving specific errors.
404 and 500 Errors when Connecting to Xero Company
If you land on the Sorry, something went wrong page when initially launching the exporter, you will see an Error code towards the bottom of said page. If it is a 404 or 500 error when connecting to Xero, follow these steps:
Check the Xero Status Page, Xero API Status Page, and HirePOS Status Page for any ongoing issues.
Log out of Xero on all tabs and log back in via login.xero.com.
You can do so by clicking your user icon (located at the right corner of the main menu bar), clicking your user icon, and then selecting the Log out button. Log back in via app.hirepos.com.
Ensure your browser is up to date. For example, refer to the following article on how to ensure Chrome is up to date.
Check with colleagues to verify if the issue is only affecting your device.
Try using a different browser. For example, if you are using Chrome, try Edge. Or if you are using Safari, try Chrome.
If using another browser works, clear your browser cache and cookies and try again.
For detailed instructions, refer to the Xero Article on 404 and 500 errors.
Clear Cache and Cookies from Google Chrome
Occasionally, weird things can happen with your browser as a result of it's cache.
You can resolve such issues, by clear your cache. Follow these steps:
Hold CTRL while clicking the refresh button to clear cache on a per-page basis.
Here are some guide for completely clearing the cache:
You will be logged out of any websites you are currently logged into after doing this.
Unauthorized Error (All Tabs)
If you encounter an unauthorized error, follow the instructions to refresh your session and resolve the issue.
Error Message | What it Means | What To Do |
---|---|---|
Response Status 401 - Unauthorized | Your Xero Exporter session has expired (has been open for more than 30 mins) | Close the tab, and open a new session by clicking the Xero button on the HirePOS Home Screen (Reminders List) |
Invoices Tab
Resolve common invoice errors by ensuring correct setup of item codes and addressing issues related to invoice exports.
Invoice Errors
Error Message | What it Means | What To Do |
---|---|---|
Cannot export Invoice No.## as item ## does not have an account number set up in the Invoice Category, Item Type, or Item Category. | You have an Item on the invoice in question that HirePOS does not have a Xero Account Code for most commonly this is due to:
|
|
Invoice already exported | This error will occur if an invoice with the same invoice number already exists in Xero. This could be the result of
Note: The conflicting invoice in Xero may be voided Note: exported invoices Can Not be updated or re-exported. | Log in to Xero and check for the invoice number in question. Check to see if it is the same invoice, or a different invoice with an overlapping invoice number.
Note: Be sure to check for voided invoices in Xero |
The Total for this document must be greater than or equal to zero. | Xero, unlike HirePOS, does not tolerate invoices with a negative total value. Documents with a negative value must be Credit Notes in order to export to Xero. |
|
The line total of ###.## does not match the expected line total of ###.## | HirePOS and Xero use a different rounding method. Usually, this error means your pricing is too specific and returns a different rounding result on each program. | Please see the article on this topic here: |
Account code '###' is not a valid code for this document. | This error can show up alongside other errors, but most commonly indicates that the specified income code does not exist in Xero, or is not the correct account type for the document. | Ensure you have entered a valid Xero account code in HirePOS, and that it relates to an account of the correct Type. |
The TaxType code '###' cannot be used with account code '###' | This error occurs when an unsuitable account has been specified (for example, you attempt to route income to an expense or cost of good sold account) | Ensure the Xero account code set in HirePOS relates to the correct type of account (Income needs to go to a revenue account in Xero) |
Document data cannot be before the Lock date | This means you've got a global lock date configured in Xero, and the record you are exporting is before this date. | See Xero's help doc on this: https://central.xero.com/s/article/Set-up-and-work-with-lock-dates |
Invoice Has been Archived | This means an invoice with the same number as the one being exported exists in Xero already, and it is archived. | In Xero, check for the invoice number in question. Check to see if it is the same invoice, or a different invoice with the same invoice number.
|
Error: 16 -QueryParseException - Syntax error. | There are one or more invalid characters in your Item Description or Customer information. Characters like quotation marks, apostrophes and ampersands can cause issues. ( " ", ' ', &) | Inspect your customer details and invoice for problematic characters. Remove or substitute any you find and try again. |
The description field is mandatory for each line item | One or more lines on the affected invoice have no description. | Add a description to the affected lines on the affected invoice and re-attempt the export |
Customer Errors
Error Message | What it Means | What To Do |
---|---|---|
Add new customer to Xero failed | Indicates an issue adding a new customer or contact to Xero. It will usually be followed by a more descriptive error | Check for a second error that may describe the issue. If not, check the customer record in HirePOS for common issues. |
Email address must be valid | The email address for the customer in HirePOS is not in a valid format (name@domain.com) | Ensure the Customer in HirePOS has a valid email address, then mark the record as pending before reattempting export. |
The contact with the specified contact details has been archived | This error usually means the customer has been archived in Xero, or had their details changed. Which can break the customer link between HirePOS and Xero | Ensure the Contact in Xero is NOT archived and verify their details match HirePOS. Next, select the problem invoice in the Xero exporter and click Mark as Pending, before re-exporting. (this will reset the customer link) |
An existing contact could not be found using the specified contact details. The contact name field is required to create a new contact | See above: The contact with the specified contact details has been archived This error usually presents itself after customer codes have been manipulated after a link has been formed with an existing customer/contact. | Select the problem invoice in the Xero exporter and click Mark as Pending, before re-exporting. (this will reset the customer link) |
The contact name cannot be empty | This can show up in the case where you have only a First or Last name for a customer (not both), or you have only whitespace (spacebar) in the Company name for the Customer in HirePOS | Open the Customer in HirePOS (Setup > Customers) and ensure you have either a Company name, or both a First and Last name entered. |
The contact name ***** is already assigned to another contact. The contact name must be unique across all active contacts; | This indicates that you are trying to export a customer with the same First/Last name or Company name combination as another customer in your system. | If these are 2 different customers, change the name of the second customer to make it unique in the system. If they are the same customer, use the merge customers tool in HirePOS to merge them into one customer. |
The account number already exists. Please enter a different account number. | The Customer Code in HirePOS the same as a Contact's "Account Code' in Xero, but not for the the matching contact. Customer Code/Account Numbers are used to connect customers and contacts between the systems, even where the contact names are not identical. | Change the Customer Code in HirePOS, and ensure the matching contact in Xero has an identical Account Number. |
How to merge customers
When creating new customers, HirePOS will warn you if the Company and/or First/Last Names are identical to any previously entered customers.
However, in the case where customers have accidentally been duplicated, they can be merged.
From the main menu strip at the top, go to Setup > Customers.
Lookup the customer you wish to merge and click the row to edit the customer. This is the customer you would like to make 'inactive' and merge with the correct 'active' customer.
In the Customer details screen, click the Options button at the top-right, then choose the Merge Customer option.
In the 'Merge With Customer' dropdown, select the correct 'active' customer you wish to merge with.
The customer's details will appear.Click the Merge Customers button to complete the process.
To be clear: The customer at the top of the screen will be made inactive, and the customer at the bottom of the screen will be kept
A warning will appear. Confirm that you are sure.
This action is not reversible.
The incorrect customer will be made inactive, and the customer's invoice and payment history will be merged with the correct customer.
Payments Tab
Resolve payment-related errors by ensuring correct payment matching and addressing issues with payment records.
Error Message | What it Means | What To Do |
---|---|---|
Invoice Number ## this payment has been applied against has Not been exported yet. | The Invoice this payment is related to does not exist in Xero yet, so there is nothing to match to. | Find the related invoice number, and export it, before attempting to export the payment record again. |
Payments can only be made against Authorised documents | Occurs when exporting payment to Xero against Invoice that has already been paid in full in Xero, or an Invoice that is still in Draft mode. | Ensure the Invoice in Xero is in a correct condition to accept the payment (Approved/Authorized, and not yet paid) |
Payment amount exceeds the amount outstanding on this document | As above. Occurs in situations where the payment amount exceeds the amount owed in Xero. Usually, this occurs when an invoice has already been paid in Xero, before attempting an export from HirePOS. | If the Invoice is already paid in Xero, and HirePOS, but you get this error:
|
Status: AUTHORISED | This error can be triggered where a refund is being attempted on an invoice that has not yet been paid. This is usually encountered around customers that are capturing bond payments as overpayments. | Contact HirePOS via hirepos@hirepos.com.au where we can have a look at your process and advise on the best practices to avoid this error. |
Status: PAID | This is an uncommon code, but is usually shown on "refund" payments when the payment is recorded in an "overpayment" record in Xero. Overpayment records are usually created when a bond record is exported before the invoice is exported, OR when bonds and full payments are exported together. | Contact HirePOS via hirepos@hirepos.com.au where we can have a look at your process and advise on the best practices to avoid this error. |
You can only record payments against AR or AP documents | You are trying to record a payment or refund against an invoice in xero that is not in an approved state (it is either a draft, or has been paid in full) | Check the status of the record in Xero, and check that you have not already recorded a payment directly. |
No Xero Code in HirePOS bank account set up to match a Xero Chart Of Accounts code | There is no Xero Code set up in HirePOS for your bank account. | Refer to this help-doc for setup instructions. |
Could not match HirePOS Bank Account Code with Xero Bank Account Code | The HirePOS bank account you are trying to use has an incorrect Xero account code assigned to it | Refer to this help-doc for setup instructions. |
The specified bank account details does not match a known bank account | As above | As above |
Account type is invalid for making a payment to/from | The Xero account that your HirePOS bank account is mapped to is not enabled to handle 'payments' | Check that you have input the correct account code in Setup > Bank Accounts. Actual bank account in Xero are able to handle payments by default, but in the case that you are intending to record your payments in an asset account other than an actual bank account, you will need to edit the account details in Xero, by enabling the option for the account Enable Payments to this Account in Accounting > Chart Of Accounts > {Account} Details |
Document data cannot be before the Lock date | This means you've got a global lock date configured in Xero, and the record you are exporting is before this date. | See Xero's help doc on this: https://central.xero.com/s/article/Set-up-and-work-with-lock-dates |
Payments (Import) Tab
Resolve import-related errors by ensuring accurate payment imports and avoiding over-payments.
Error Message | What it Means | What To Do |
---|---|---|
Cannot import as it would result in an overpayment | The value of the payment you are trying to import is greater than the value outstanding on the invoice in HirePOS. This is usually the result of manually entering payments at both ends (or attempting to reconcile Pin Payments payments using Xero Bank Recs) | Check the payment status of the Invoice in question in both Xero and HirePOS. If they are both paid, with similar payment dates and identical amounts, you can disregard this import suggestion.If they are different, and the Xero payment record is accurate, Delete the payment record in HirePOS, and then import the Xero Record. |
Cannot export invoices
If you cannot export sales records because they are greyed out and have a red circle-backslash symbol, with no corresponding error message, this is likely because the Use Draft/Approval Process for invoicing restriction turned on. The purpose of this restriction is to prevent un-finalised records from being exported.
If this setting has been turned on by mistake, an admin can turn it of via Setup > Preferences > Restrictions. Before doing so, please confirm with the appropriate staff before doing so.
Further Assistance
For further assistance or detailed instructions, contact HirePOS support at hirepos@hirepos.com.au.