Common Xero Export Errors

Edited

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:

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:

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:

  • No Account Code set at the Item Type or Category level

  • The line has been freely typed on to the invoice (No Item Code selected)

  • Check that your Income Codes are set up correctly.

  • Make sure each line of your invoice has an item code selected.

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 

  • your HirePOS invoices overlapping unrelated existing invoices in Xero, or 

  • you may have legitimately exported this invoice before (and subsequently marked it as ‘pending’) 

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.

  • If it’s the same invoice, mark the invoice in the exporter as Complete

  • If it is different, consider adding a letter to the Inv # to make it unique.

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.

  • If you intend to export an invoice, correct the invoice total value to a positive number and reattempt export

  • If you intend to export a Credit Note, open the invoice in HirePOS and convert it to a Credit Note before reattempting export.

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.

  • If it’s the same invoice, mark the invoice in the exporter as Complete 

  • If it is different, consider adding a letter to the Inv # in Xero to make it unique.

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.

  1. From the main menu strip at the top, go to Setup > Customers.

  2. 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.

  3. In the Customer details screen, click the Options button at the top-right, then choose the Merge Customer option.

  4. In the 'Merge With Customer' dropdown, select the correct 'active' customer you wish to merge with.
    The customer's details will appear.

  5. 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

  6. A warning will appear.  Confirm that you are sure.

    This action is not reversible. 

  7. 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:

  • mark the payment export record as completed, OR

  • delete the duplicate entry in HirePOS and then perform a payment import from Xero

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.