Troubleshooting Xero Exports

Learn how to identify Zanda-created contacts in Xero, handle common errors, merge duplicate contacts, and resolve export issues for smooth integration.

In this article:

• How to tell which Xero contacts have been created by Zanda
• The Account Number already exists or another contact has this Contact Number
• The Contact Name already exists. Please enter a different Contact Name
• Duplicate Contacts in Xero
• Invoice not of valid status for modification
• Invoice not of valid status for modification, this document cannot be edited as it has a payment or credit note allocated to it
• Payments can only be made against authorised documents
• Export failed. An unexpected response was received from Xero
• Unable to export invoices as Approved or export payments
• Bank account status invalid for payment creation
• GST Free tax codes export as BAS Excluded in Xero
• Branding Theme with ID doesn't exist
• You have reached the limit of invoices you can approve
• To update fields on a paid invoice line item, you must supply a LineItemID
• You are connected to a different Xero Organisation
• Invoice or Payment is in Xero Locked Period
• Account code 'xx' is not a valid code for this document

How to tell which Xero contacts have been created by Zanda

Contacts in Xero that have been created by Zanda will have a Contact Code (see the red arrow on the picture below).  This is the Client Number from Zanda.  Xero does not allow users to edit this number.

The Account Number already exists or another contact has this Contact Number

If you already have contacts in Xero that use the same Contact Number or Account Number, then you will see these messages in Zanda:

1. "The account number already exists, please enter a different account number"
2. "Another contact has this contact number, please enter a different contact number"

This means that there is already an existing contact in Xero with the same Account Number or Contact Number as the one you are trying to export from Zanda.  

The Account Number / Contact Code can be seen in Xero by editing the contact. The Client Number in Zanda can be found by looking at the Client details screen.

The most common cause of this issue is that you have archived the Contact in Xero. Review your archived contacts in Xero and you will probably see one in there that matches the details of the Client you are trying to export from Zanda.

Un-archive this contact and merge them with any other similar ones you may have in Xero, keeping the contact with the Contact Code / Account Number.

The Contact Name already exists. Please enter a different Contact Name.

This indicates that there is a profile in Xero that has this same name combination and therefore this profile cannot be exported. Please check in Xero by searching all Contacts (both  archived and unarchived) to determine if the profile is a duplicate or not. If so, you can use the steps in the section below to remedy this.

A key method to link the client profile in Zanda to the profile in Xero to ensure that the data exports into that Xero contact is to update the Xero Contact ID in the client profile. Steps on how to do this are listed below:

1. Go into Zanda and access the client profile you are exporting the invoices/payments for.
2. Navigate into Admin > Manage. On this page, you'll see a field 'Xero Contact ID' (if you don't see this field, try setting the Role on this page to include 'Client' and then save, and this should then display the field).
3. Access your Xero account and view the contact profile that you would like this client's data to export into. Your URL should look something like: https://go.xero.com/Contacts/View/XXXXXXXXX-XXXX-XXXX-XXXX-XXXXX
4. Highlight and copy all characters showing after https://go.xero.com/Contacts/View/
5. Paste this code into the 'Xero Contact ID' field in the client profile in Zanda and click 'Save Changes'.
6. try refreshing your Xero export and attempt to export this client's data.

Duplicate Contacts in Xero

If you use the Company Name field in Zanda and then export invoices for this client, Xero will create a new contact using the Company Name as the Contact Name. In the example below, the company name in Zanda was ABC Pty. Ltd. and the Client name was Damien Test.

If you later remove the company name from Zanda and then export more invoices, Xero will attempt to rename the contact to the Client Name. In this example, it would change ABC Pty. Ltd. to Damien Test.

If you already have an existing contact in Xero with this same name (Damien Test) the export will fail because Xero will not allow multiple contacts to have the same name. You may see an Export Result message which reads as follows:

"The existing contact with name 'ABC Pty. Ltd.' cannot be updated to use new name 'Damien Test'. There is an existing contact with that name"

The solution is to merge the contacts in Xero, keeping the Zanda created contact.  See above for how to find out which contact was created by Zanda.

Invoice not of valid status for modification

You have tried to export the invoice in Draft status when it's already in Xero with another Status. Alternatively, this may mean that you're trying to export payments onto an invoice in Draft status (it needs to be set to approved first).

Invoice not of valid status for modification, this document cannot be edited as it has a payment or credit note allocated to it

The invoice is already in Xero and has payments recorded in Xero.

Payments can only be made against authorised documents

This error indicates that the invoice you are trying to export the payment against has been exported as a Draft status, rather than as Approved. To remedy this you will need to export the invoice(s) again and ensure that they're exported as Approved (this is selected at the bottom of the page). Once they're in Xero as Approved you should be able to export the payments onto them.

Export failed. An unexpected response was received from Xero

1. Disconnect from Xero by clicking on this button:

2. Navigate to Tools → Xero Export and connect to your Xero account again. 

Unable to export invoices as Approved or export payments

Xero Cashbook and Ledger plans are not able to receive invoices or bills from third-party apps, therefore, you won't be able to export Approved invoices or payments to Xero if you are under these plans. These plans will only support exporting invoices as Draft status. You will need to upgrade your plan with Xero to enable the export of Approved invoices and payments.

Bank account status invalid for payment creation

This error means that the bank account the payments were synced to no longer exists. It may have been deleted, archived or edited in some way that disrupted the sync.
To resolve this, please,

1. Correct this in Xero.
2. Re-map the payments to the correct account, via Tools → Xero Export → Xero Settings  → Xero Payments Account.

GST Free tax codes export as BAS Excluded in Xero

This can happen if the Tax Usage in invoice settings is set up to No Tax.

1. First of all check the invoice configuration settings, to make sure that all the invoices you will generate afterward will have the correct tax usage preset:

• Go to Settings > Billing > Invoices. 
• How to calculate Tax - select Price Includes Tax or Price Excludes Tax;
• Save changes.
  

2. The already existing invoices will have to be updated manually. Please

• Open each invoice;
• On the right-hand side, select Tax Usage as  Price Includes Tax or Price Excludes Tax;
• Save changes.
  

Branding Theme with ID doesn't exist

1. Please go to Tools → Xero Export, click Xero Settings (blue button on the right), and ensure that a Xero Branding Theme has been set.
2. Once done, click the Save button and try to re-export.

You have reached the limit of invoices you can approve

There are two possible reasons for this error:

1. If you are on a trial of Xero, there is a limit of 10 accounts receivable and 10 accounts payable invoices that can be set to 'Approved' in Xero.
2. If you have the Small Business Edition of Xero, there are also limits to the number of invoices you can approve according to http://www.xero.com/pricing

To update fields on a paid invoice line item, you must supply a LineItemID

This error message means that Service Item Code is missing or has invalid values rather then just numbers.

To update fields on a paid invoice line item, you must supply a LineItemID, Date cannot be changed on an invoice that has payments or credit notes allocated to it., The status AUTHORISED cannot be applied to the invoice because it has payments or credit notes allocated to it

This means the Invoice has not been sent over as approved to Xero since adjustments were made to the Invoice (after the first export). You will need re-exported the Invoice as approved.

You are connected to a different Xero Organisation

"You have connected to a different Xero organisation than the one that was used to create these settings, so please either update the values below and click 'Save' or else disconnect and reconnect to the correct Xero organisation"

This notification may come up when 

a) you are linking Zanda to your Xero account for the first time. In this case, click on the Xero Settings button on Zanda > Tools > Xero Export page and complete setting your integration. 

b) switching to a different Xero organisation. In this case: 
1. In  Zanda > Tools > Xero Export, disconnect from Xero. 

2. Go to your Xero account > Settings > Connected Apps and remove the Zanda app you will see there. 

3. Go to  Zanda > Tools > Xero Export and connect to the correct Xero organisation. 

Invoice or Payment is in Xero Locked Period

This message indicates that an invoice date or its payment date are within the locked period when changes to the transactions are not allowed. To resolve this, 

1. In Xero account, remove or update lock dates as necessary;
2. In Zanda > Tools > Xero Export, disconnect from Xero, then connect again. 
3. Export invoices and payments to Xero. 

Account code 'xx' is not a valid code for this document

This error occurs when attempting to export to a Sales account that has been removed or edited in the connected Xero account.

To resolve this issue, navigate to Tools > Xero Export > Xero Settings and review the default Sales account and any Sales accounts mapped under Map to Diary. Ensure these fields are updated and none are left blank.

The error arises if the Xero account is connected, Sales codes are configured and saved, but the associated Sales account is later edited or deleted in your Xero account. In such cases, your Zanda account settings retain the previous Sales code, which are then used during export, resulting in an error. Additionally, the Sales account name may appear blank, as Zanda cannot retrieve details for a Sales account that no longer exists in Xero.