An invoice failed to sync with Xero

Some of the common reasons why Xero will give you an error message when syncing an invoice.

Emily avatar
Written by Emily
Updated over a week ago

While it would be awesome if every invoice was able to sync over to Xero without issue, there can be some instances that it won't work. These can vary, and in this article we'll provide details about why an invoice would fail to sync, and what can be done about it!


Why would an invoice not sync with Xero?

There can be numerous reasons as to why an invoice would fail to sync with Xero, and every time it happens, you'll get an email from Cliniko, letting you know which invoice failed to sync, and why this was. The email will include an error message (this is what Xero provides to us when it blocks the invoice from entering your account), and below, we'll outline what can be done to fix these errors!

Below is a list of errors; click each one to check out what it means, and how to fix it:


Can I resync an invoice if it fails?

In most cases, yes! 

As long as the invoice doesn't exist in Xero whatsoever, you can resync it simply by editing it and saving it (with or without making changes).

If the invoice already "lives" in Xero (and has been marked as paid), then you will need to make modifications in Xero. This is because once Xero sees an invoice is paid, it won't let Cliniko send over any additional changes!


Payments can only be made against Authorised documents.

The problem: This invoice—which is marked as paid—has already been synced to Xero, but something has triggered it to have an attempted resync.

The reason: This paid invoice was modified in Cliniko, after it has already been synced over to Xero. It might be as little as editing the invoice to change a note on it, or as big as changing the billable item.  Xero locks us out from making any changes to the invoice in Xero after it is paid. Therefore, you'll get this error if any changes are made to the paid invoice, post-sync.

The solution: Nothing to do, actually! If everything is looking right and balanced across the two systems, then it's likely the invoice was edited for a small reason, and you can ignore this error.


You have reached the limit of invoices you can approve.

The problem: Your Xero account won't let you have any more approved invoices. 

The reason: You're still on the trial version of Xero, or on their "Starter" plan. Both of these will impose a limit on the number of approved invoices that you can have in Xero. Read more on their website.

The solution: Move off the trial version of Xero, or upgrade your plan to the next level. Then you'll be able to sync your invoices!


The document date cannot be before the period lock date.

The problem: An invoice is dated before the "lock date" (an end-of-period date set in your Xero account). 

The reason: Xero sees this period as closed, so it won't "accept" any invoices that are dated prior to it (hence the date being "locked").

The solution: Change the lock date in Xero and then resync your invoices from Cliniko. Check out Xero's information on working with lock dates here!


The document date cannot be before the end of year lock date.

The problem: An invoice is dated before the "lock date" (and end-of-year date set in your Xero account).

The reason: Xero sees this period as closed, so it won't "accept" any invoices that are dated prior to it (hence the date being "locked").

The solution: Change the lock date in Xero and then resync your invoices from Cliniko. Check out Xero's information on working with lock dates here!


This document cannot be edited as it has a payment or credit note allocated to it.

The problem: The invoice is already in Xero, and is marked as paid. This same paid invoice in question has been edited in Cliniko. When an invoice is edited after it's been synced, a resync will be automatically attempted.

The reason: Once an invoice has been synced to Xero and is marked as paid, Xero will lock Cliniko out of sending any changes over. 

The solution: You will need to make the changes to the invoice in your Xero account. You can learn how to edit a paid invoice in Xero here.


Email address must be valid.

The problem: The patient's email address is different in Cliniko than it is in Xero.

The reason: The email address of the patient may have been edited in Cliniko at some point (if the address changed, for example).

The solution: Make sure that the patient's email address are the same in both Cliniko and Xero! They need to be exactly the same. Xero's term for patients is "contacts"; they talk about how to update a contact's details (including changing the email address) here.


Invoice not of valid status for modification.

The problem: There is already an invoice with this number in Xero. 

The reason: This invoice (well, an invoice with the same number, at least) has been added to Xero somehow—either via the Cliniko/Xero integration, or it was manually added into the Xero account directly.

The solution: You will need to find this invoice in Xero and amend it accordingly. It will have the same number, but it might not necessarily be the same invoice (for the same patient, with the same amount, etc.). If you don't find it in your list of invoices, it might be voided—be sure you check for voided invoices, as well!


The existing contact with name 'CONTACT NAME' cannot be updated to use new name 'NEW NAME'. There is an existing contact with that name.

The problem: The name of this patient in Xero doesn't match the name in Cliniko. 

The reason: The patient's name was changed in Cliniko without also updating it in Xero, which means a new contact with the new name was created in Xero. Typically, this happens if the patient's name was spelled incorrectly in Cliniko, and this was realised and corrected after at least one invoice had been synced over.

The solution: In Xero, find the patient (called Contacts in Xero) that has the correct name. Archive that contact. (Don't worry—this won't break anything!) Now, in your list of archived contacts, find the original contact that has the incorrect name. Restore that contact, then update the name to match what you have in Cliniko, and then resync the invoice!

For example, let's say you get an error from Xero that says:

The existing contact with name 'Jon Smith' cannot be updated to use new name 'John Smith'. There is an existing contact with that name. 

The patient's name is currently "John Smith" in Cliniko, but when originally added, it was entered as "Jon Smith". An invoice was synced over for "Jon Smith", but then a week later, it was realised that he actually spelled his name with an "h"—so it was changed to "John"!

Now, another invoice was raised for "John Smith" in Cliniko, but Xero sees that although this mysterious "John" has the same unique "Contact ID number" (something that only Xero can see), the name isn't "Jon" anymore! So Xero's like, what gives, dude? (And that's why it sends that error back!)

When you find the original "Jon" in Xero, and change him to "John", Xero now knows that this is indeed the same John, and will now accept invoices for him!


The status 'DELETED' is not valid for contacts.

The problem: The patient that this invoice is for has been archived in Xero.

The reason: If a patient gets archived in Xero and Cliniko tries to send an invoice over for that patient, Xero will think the patient is no longer active (since it's been archived) and won't accept the invoice.

The solution: Restore the patient in Xero. Keep in mind that Xero calls the patients "contacts", so you would be restoring a contact. Xero talks about how to restore a contact here.


Item Code is not valid.

The problem: The item code is different in Cliniko than it is in Xero.

The reason: The item code of the product or billable item may have been edited in Cliniko at some point after we've already sent the item information over to Xero. 

The solution: Head to the Products and services area in Xero (Xero → Business → Products and services), and find the billable item/product that is causing the issue. Change the item code in Xero so that it matches exactly with the item code in Cliniko. After that, you can then re-sync any invoices by editing an invoice, then saving it without making any changes!

Did this answer your question?