Integration
Why did my Cliniko invoice fail to sync with Xero?
Cliniko's help centre lists ten specific error messages that stop an invoice reaching Xero. The most common are an archived or renamed Xero contact, a duplicate or already approved invoice number, an invalid patient email, an outdated item code, and an invoice dated before a Xero lock date. Each message points to one fix.
Last checked 25 Sep 2026 against the sources listed at the end of this page.
Symptom: An invoice you create or edit in Cliniko does not appear in Xero, or Cliniko shows a specific error message next to the invoice instead of syncing it quietly in the background.
Causes, most common first
The patient's contact record is archived in Xero, which Xero reports as 'the status DELETED is not valid for contacts'.
Check: Search Xero Contacts, including archived contacts, for the patient's name.
Fix: Restore the contact in Xero, then resync the invoice from Cliniko. This has to be fixed in Xero; Cliniko cannot revive an archived Xero contact from its side.
The patient's name was changed in Cliniko but not in Xero, or the other way round, so Xero refuses the update with 'the existing contact with name X cannot be updated to use new name Y'.
Check: Compare the patient's name as it appears on the Cliniko invoice against the matching Xero contact.
Fix: In Xero, archive the mismatched contact, restore the correct one if it already exists, or rename the Xero contact to match Cliniko exactly, then resync.
The invoice number already exists in Xero as an approved or voided invoice, which Xero rejects as 'invoice not of valid status for modification'.
Check: Search Xero for the invoice number Cliniko is trying to send, including voided invoices.
Fix: Find the duplicate in Xero and amend or renumber it, then resync from Cliniko.
The patient's email address on the invoice is missing, misspelled or does not match Xero's format requirements, which Xero flags as 'email address must be valid'.
Check: Open the patient's Cliniko profile and check the email field for typos or a blank entry.
Fix: Correct the email in Cliniko so it matches the format Xero expects, save the patient record, then resync the invoice.
A billable item's item code was changed or removed in Xero's Products and services list after the invoice was created, which Xero reports as 'item code is not valid'.
Check: Compare the item code on the Cliniko billable item against Xero's Products and services list.
Fix: Update the item code in Xero so it matches Cliniko exactly, or update Cliniko to use a code that still exists in Xero, then resync.
The invoice is dated before Xero's period lock date, which Xero rejects as 'the document date cannot be before the period lock date'.
Check: Check the invoice date in Cliniko against the lock date set in Xero under financial settings.
Fix: Move the lock date in Xero if the period genuinely needs to reopen, then resync the invoice from Cliniko.
The invoice is dated before Xero's end of year lock date, a separate setting from the regular period lock date.
Check: Check whether the invoice falls in a financial year Xero has locked for end of year reporting.
Fix: Adjust the end of year lock date in Xero with your accountant's agreement, then resync.
The Xero invoice already has a payment or credit note allocated to it, so Xero blocks Cliniko's edit with 'this document cannot be edited as it has a payment or credit note allocated to it'.
Check: Open the invoice in Xero and check whether a payment or credit note is already recorded against it.
Fix: Make the correction directly in Xero. Cliniko cannot push further changes to an invoice Xero already treats as settled.
Xero rejects the sync with 'payments can only be made against authorised documents', usually after a small edit to an invoice that is otherwise already correct in both systems.
Check: Compare the invoice total and status in Cliniko against Xero.
Fix: If the two systems already agree and the balances match, no action is needed; Cliniko's help centre treats this message as safe to ignore once everything reconciles.
Your Xero plan has reached its invoice limit, which Xero reports as 'you have reached the limit of invoices you can approve'.
Check: Check your Xero plan tier against the number of invoices approved this month.
Fix: Upgrade the Xero subscription to a plan without an approved invoice cap, then resync.
Start with the exact wording
Cliniko does not show a generic failure. Each rejected invoice carries the message Xero sent back, and Cliniko's help centre maps ten of these messages to a specific cause each. Reading the wording first saves time, because half of these causes are fixed inside Xero and Cliniko has no way to force them through from its side.
Cliniko's own guidance treats one of the ten as harmless: "payments can only be made against authorised documents" often appears after a small edit to an invoice that is already correct in both systems, and if the totals already match there is nothing to do.
Contact mismatches are the most common group
Three of the ten causes come down to the Xero contact not matching the Cliniko patient: the contact archived, the name changed in one system but not the other, or the email address wrong. These all have to be corrected in Xero itself, not Cliniko, because Cliniko is only pushing a name and email it already holds; Xero is the one refusing to accept the update.
Keeping patient names identical in both systems avoids this entirely. If your bookkeeper regularly tidies up the Xero contact list, agree with them that Cliniko patient contacts are off limits for archiving or renaming without checking Cliniko first.
Lock dates and settled invoices need a different fix
Two causes are date related: an invoice dated before Xero's period lock date, and one dated before the separate end of year lock date. Both need the lock date moved in Xero, which is usually a decision for your accountant rather than the front desk, since lock dates exist to stop the numbers changing after a return has been lodged.
A third group is invoices Xero already treats as final: once a payment or credit note is allocated to an invoice in Xero, Cliniko can no longer edit it, and the correction has to happen directly in Xero.
Sources
- Cliniko's help centre lists specific Xero error messages an invoice can return, including contacts archived in Xero ('the status DELETED is not valid for contacts') and mismatched contact names ('the existing contact with name X cannot be updated to use new name Y'). Cliniko Help, checked 25 Sep 2026.
- An invoice dated before Xero's period lock date or end of year lock date is rejected until the lock date is changed in Xero and the invoice is resynced from Cliniko. Cliniko Help, checked 25 Sep 2026.
- An invoice with a payment or credit note already allocated to it in Xero cannot be edited from Cliniko; the correction has to be made directly in Xero. Cliniko Help, checked 25 Sep 2026.
- A duplicate invoice number already existing in Xero, an invalid patient email address, and an item code no longer valid in Xero's Products and services list are each listed as separate causes of a failed sync. Cliniko Help, checked 25 Sep 2026.
- Approving a Cliniko invoice creates an invoice in Xero, which is blocked once a Xero plan's approved invoice limit is reached, requiring an upgrade to a plan without that cap. Cliniko Help, checked 25 Sep 2026.