Common Xero Export Errors

The Xero Exporter will usually work without a hitch. However, when first setting it up, and when starting to export more detailed invoices, you are likely to get some errors that will help guide you in completing and perfecting your setup. Below are a series of common errors, a look at what they mean, and how to best correct them.

Error: Response Status 401 - Unauthorized

This will happen if it has been longer than 30 minutes since you made the connection to Xero, or if your session has otherwise been interrupted.

Close the tab, and open a new session by clicking the Xero button on the HirePOS Home Screen (Reminders List)

Error: Cannot export Invoice No.## as item ## does not have an account number set up in the Invoice Category, Item Type, or Item Category.

This indicates that the item indicated is not a member of a type or category that has an account code assigned to it. This is required to Xero knows what account to assign the income to.

Ensure that the Item is a member of a Category or Type that has a Xero Account Code set.

For more information see Xero API.

This error will also occur if you have freely written onto an invoice line as a 'message' or 'heading' without selecting an item from the 'code' dropdown. Although this is a great way to organise and customize invoices quickly, it is not a compatible practice with Xero.

Error: Add new customer to Xero failed

Error: Email address must be valid.

This will occur if you have an email address set for the customer that is not a normal format (***@***.***). Please ensure that you have set a valid email address for the customer before trying again.

Error: Invoice already exported.

This indicates that the record has already been exported, or more specifically, a similar record (with same invoice number) exists in Xero already. This is the primary reason is it best practice not to export on-hire invoices, incase the value should change slightly on return, in which case it cannot be re-exported.

The line total of ***.** does not match the expected line total of ***.**.

This is an indication that the rounding involved in your pricing has become to specific for HirePOS and Xero to agree on automatically.

Please see the article on this topic here: Xero Rounding Account

Error: The contact with the specified contact details has been archived

When HirePOS exports the customer to Xero as a 'contact' in Xero for the very first time, it tracks the unique id for the contact returned back from Xero.  Any subsequent invoices are then exported using the unique id rather than attempting to re-export the contact again.

If you archive the contact in Xero, then HirePOS is still using the same contact id and Xero will return an error as you cannot export Invoices to an archived contact.

To resolve this, your first step is to click the Checkbox of the particular invoice in the exporter and click the Mark As Pending button.  This will clear any link that HirePOS has to the contact and attempt to rematch to an active contact when you export.
Failing this, set up a unique "Customer Code" in HirePOS that matches the same unique "Account Number" against the contact in Xero.  HirePOS will then use the Code/Account numbers to link the contact rather than the "name" and you should not have any issues linking the contact at all. 

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

Please see above "Error: The contact with the specified contact details has been archived"


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 in the case where bonds and full payments are exported together.

The recommended remedial action is to manually process the refund for the overpayment in Xero, and mark the refund/payment record in the HirePOS/Xero exporter as "complete".

Status: PAID

Similar to Status:AUTHORISED (above).

Manually process the payment/refund at the Xero end, and mark the local HirePOS record as Complete in the HirePOS/Xero Exporter.

Error: Payment amount exceeds the amount outstanding on this document

This error usually occurs in the instance where an invoice has been marked as paid in Xero via a bank rec, and ALSO marked as paid manually in HirePOS before any Payment Imports have occured.

If this is the case, simply mark the payment export record as completed, or delete the duplicate entry in HirePOS and then perform a Payment (Import) from Xero

Invoice Number ## this payment has been applied against has Not been exported yet.

This will occur if you attempt to export a payment before the invoice the payment was made against has not yet been exported.

It is best practice to export your invoices first, and then export your payments.

If you have received a payment for an on-hire invoice, and you are not exporting on-hire invoices (is it generally best practice not to), you will need to leave this one in the list until the invoice can be exported.

In the case of partial payments in advance (deposits, for example) consider creating separate invoice records for the deposit component. See Deposits Received in Advance. The resulting invoices and payments will be freely exportable.

Error: No Xero Code in HirePOS bank account set up to match a Xero Chart Of Accounts code.

This error will present itself when you have not assigned a Xero Account Code to the bank account used for the payment in question. Navigate to Setup > Bank Accounts and add the Xero Account Number (in Xero: Accounting > Chart of Accounts) for the bank account you are using.

Error: Could not match HirePOS Bank Account Code with Xero Bank Account Code.

It is likely that the HirePOS bank account you are trying to use has an incorrect Xero account code assigned to it.

Error: The specified bank account details does not match a known bank account

It is likely that the HirePOS bank account you are trying to use has an incorrect Xero account code assigned to it.

Error: Account type is invalid for making a payment to/from

The Xero account that your HirePOS bank account is mapped to is not enables 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

Error: TaxType code - The operation has timed out' cannot be used with account code '4200'.

Cross-check the Xero Tax (Income) field in HirePOS in Setup > Tax Codes vs the Tax Description in the Xero app tax setup.

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

Contact/Invoice Has been Archived.

This means that the Contract/Invoice has been Archived, or Deleted in Xero.

IF this is an Invoice:

This must mean, an "Invoice 32" exists in Xero already, and it is archived.

Should be able to search for it in Xero, just need to have this box checked.

IF this is a Contact:

You'll need to compare the customers details in HirePOS, to Xero.

Sometimes, there might be multiple duplicate contacts in Xero. one if which might be archived

HirePOS Matches by Code/ Company / First name/ Last name.

If you get this error, it's probably trying to export the invoice to an Archived contact, and not the actual contact you want.

In which case, you'll need to give the contact in Xero an Account code and then back in HirePOS, give that customer a matching Customer code.

They will be matched by that instead, once you mark the record as pending, and export again.

Did this help?

Powered by HelpDocs (opens in a new tab)