When an invoice fails to sync with Xero, an error appears in the Xero status card on the invoice; open the invoice and look for the sync status and error message. Find your error below and follow the steps to resolve it. Each error is shown with the exact wording Xero returns, so you can match what you see on screen.
If the same invoice keeps failing after retrying, check that every step has been completed in both splose and Xero; a change in one system is not always reflected automatically in the other.
How to use this guide
Copy the error text from the Xero status card, then find the matching heading below. If your exact wording isn't listed, read the closest match; the cause is usually the same. If nothing matches or the error persists after you've followed the steps, jump to Still failing? When to contact support at the end.
Before you begin
Many sync errors clear after a couple of quick checks. Before working through the errors below, confirm:
The Xero connection is active. Go to Settings > Integrations > Xero. A disconnected or expired connection will stop invoices syncing; reconnect if needed.
The invoice has left Draft. An invoice only syncs once it's marked as sent and moves to Awaiting Payment.
You've re-synced. Go to Workspace Settings > Integrations and click Settings on the Xero tile. To re-sync one invoice, click Sync Now next to it; to re-sync several, tick their checkboxes and click Sync Selected.
If the invoice still won't sync after these checks, find your error message below.
Common Xero error messages
Account and tax code errors
Account code not valid
Error
The Xero account used on the invoice (or the integration default) is not a valid Revenue account. Common wording includes:
"Account code '100' is not a valid code for this document"
"Account code not valid (10010)"
"Account code or ID must be specified"
"199 is not a valid account code"
"Account code 110 not a valid Revenue account"
"(Add account code in Xero)"
"Can't sync with Xero because the account doesn't exist"
Bank-account variants: "bank account has no account code" / "the bank account status invalid for payment creation"
Work through the causes below in order.
How to fix it
Cause 1: The default invoice items account is a Bank account, not a Revenue account
The Default Xero account for invoice items must be a Revenue-type account. If it is set to a Bank account, every invoice using that default will fail.
Go to Settings.
Click Integrations, then Xero settings.
Locate Default Xero account for invoice items.
Change it to a Revenue-type account from your Xero chart of accounts.
Click Save.
Then update the account on each affected service:
Go to Settings, then Services.
For each service linked to a failed invoice, click Actions (three dots), then Edit.
Scroll to the Xero invoice account field.
Select a valid Revenue-type account, or leave it empty to use the integration default set above.
Click Save.
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Cause 2: The invoice items account and payments account are the same Xero account
The Default Xero account for invoice items and the Default Xero account for payments must be two different accounts. Using the same account for both will cause invoices to fail.
Go to Settings.
Click Integrations, then Xero settings.
Check the Default Xero account for invoice items and Default Xero account for payments fields.
Ensure they are set to two different accounts.
Click Save.
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Cause 3: A service is using a non-Revenue account at the service level
A specific service may have an invalid account set at the service level, overriding the integration default.
Go to Settings, then Services.
Locate the service related to the failing invoice and click Actions, then Edit.
Scroll to the Xero invoice account field.
Update it to a valid Revenue-type account, or leave it empty to fall back to the integration default.
If the invoice includes products, go to the Products tab and ensure each product also has a valid Revenue-type account selected.
Click Save.
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Cause 4: The Xero bank/clearing account has no account code (payments and credits)
For payment and credit sync, the Xero bank or clearing account itself must have an account code.
In Xero, go to Accounting, then Chart of accounts.
Edit the relevant bank/clearing account and give it an account code.
Re-sync the invoice. To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Still failing? If every account is a valid Revenue account and the error persists, it may be a backend sync fault — see Still failing?
The tax code cannot be used with this account code
Error
Xero rejects the combination of tax rate and account code on the invoice. Common wording includes:
"The TaxType code 'EXEMPTOUTPUT' cannot be used with account code '310.2'"
"The tax code EXEMPT OUTPUT cannot be used for account code 447"
How to fix it
The tax rate assigned to the service isn't valid for that Xero account.
Go to Settings, then Services, and open the service on the failing invoice (Actions, then Edit).
Change either the tax rate or the Xero invoice account to a combination Xero accepts. (If unsure which combinations are valid, check the account's default tax rate in Xero's chart of accounts.)
Click Save.
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Payments, credits, and reconciliation
Invoice not marked as paid in Xero
Error
A payment recorded in splose has synced to Xero, but the invoice still shows as unpaid in Xero (or a payment reconciled in Xero still shows the invoice as unpaid in splose). This is not a sync failure; the invoice synced correctly, but the bank payment in Xero has not been matched to it. Paid status updates only when the bank payment is matched to the synced invoice.
How to fix it
In Xero, go to Accounting, then Bank accounts.
Open the relevant bank account and locate the payment in the bank feed.
Click Find & Match.
Match the bank feed entry to the synced splose invoice.
Click OK to reconcile. The invoice will then show as paid in splose.
Set your defaults once so this is smoother next time:
Go to Settings, then Integrations, then Xero and set the default payment account and how reconciled payments are recorded.
If the invoice still shows as unpaid after completing these steps:
In Xero, click Remove and Redo on the reconciled entry.
Redo the reconciliation with Find & Match against the invoice again.
⚠️ Bulk / lump-sum payments
If a single payment was reconciled across many invoices (for example 200+ invoices in one lump sum), Remove and Redo re-does the entire batch and can hit Xero's daily API limit. There is currently no per-invoice force-resync. If you're dealing with a large batch that won't update, contact the splose support team rather than repeatedly retrying.
Credit or write-off not synced
Error
Credits and write-offs are one-way. They sync from splose to Xero, but credits or overpayments created directly in Xero do not sync back to splose. This leaves the invoice unpaid in splose and can show as:
"Credit not synced"
"Credits not synced"
How to fix it
Always create credits and write-offs in splose first, not directly in Xero.
If you have not yet created the credit:
Go to the client's profile in splose, then Payments.
Add a payment for the credit amount, and set each invoice allocation to 0.00 so the balance becomes an unallocated credit.
Apply it to the invoice via Pay, then Pay with credit.
Once the credit syncs to Xero, use Find & Match in Xero to reconcile the bank feed against both the invoice and the credit.
If you have already created the credit in Xero:
Remove the credit from Xero (contact Xero support if you're unsure how).
Recreate it in splose via the client's Payments as above.
Once it syncs to Xero, reconcile with Find & Match.
For a bad debt/write-off: recreate the write-off in splose rather than expecting a Xero-created one to sync back.
⚠️ Voiding credits is not two-way. To void a credit, do it in both splose and Xero separately.
Connection and Xero plan
Xero connection has expired
Error
An invoice fails because the connection to Xero has expired, or your Xero organisation is on a Cashbook or Ledger plan, which doesn't support invoicing via the API.
How to fix it
If the connection has expired:
Go to Settings, then Integrations.
Click Xero.
Disconnect the existing connection and reconnect by following the on-screen prompts.
If your Xero plan is Cashbook or Ledger:
Upgrade your Xero plan to one that supports invoicing, or contact your accountant or bookkeeper to discuss your options.
Note: Xero connections can expire without warning. If invoices suddenly stop syncing across the board, check the connection here first. If reconnecting repeatedly fails, or you see "We could not find the organisation" or "Missing tenant ID", it's a backend issue — see Still failing?.
You have reached the limit of invoices you can approve
Error
Your Xero subscription has a cap on the number of invoices you can approve (for example, on the Ignite plan). This is a Xero limit, not a splose error.
How to fix it
Upgrade your Xero plan to one that supports a higher invoice volume.
Contact and client details
The contact name is already assigned to another contact
Error
Xero won't accept two contacts with the same name. Common wording includes:
"The contact name is already assigned to another contact"
"The contact number Patient-… is already assigned"
This often happens when the same client exists twice, for example after online or QR-code bookings created a duplicate.
How to fix it
Edit one of the clients (in splose or Xero) so the name is slightly different, for example, "Simon Marshall (2)".
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
If the duplicate came from online/QR bookings, merge the duplicate clients first: open the client, then Actions, then Merge. To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
The contact must contain a name, ContactID or ContactNumber
Error
The invoice recipient in splose is missing a name. Xero needs at least a name to create or match a contact. Wording is usually:
"The contact must contain at least 1 of the following elements to identify the contact: Name, ContactID, ContactNumber"
How to fix it
Open the failing invoice and check who it's addressed to: the client directly, or a contact (such as a parent, organisation or funding body).
Open that recipient's record and make sure their first and last name are fully completed.
If the invoice is addressed to a contact, go to Contacts in the left-hand menu, find the contact, and confirm their name is saved correctly.
Once the name is saved, re-sync the invoice. To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Duplicate, locked, or allocated invoices
Invoice number must be unique
Error
An invoice with the same number already exists in Xero. Wording is usually exactly:
"Invoice number must be unique"
How to fix it
Option 1: Change the invoice number in splose (simplest)
In splose, open the invoice that failed to sync.
Edit the invoice number to a value that does not already exist in Xero.
Save the invoice.
To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
Option 2: Resolve the conflict in Xero first
In Xero, go to Business, then Invoices.
Search for the duplicate invoice number. If you can't find it, select Include deleted & voided and search again.
Edit the existing Xero invoice and change both the Reference number and Invoice number to something unique (for example, if the invoice is INV-0002, change both to INV-XXX2).
Delete this invoice from Xero.
Re-sync (Sync with Xero on the invoice, or Sync Now/Sync Selected on the Xero integration page). This creates the invoice fresh in Xero.
⚠️ There is no clean path when the conflicting invoice has already been paid in Xero. If the paid invoice can't be changed or voided, contact the splose support team. (See also the related error: "The status VOIDED cannot be applied to the invoice because it has payments or credit notes allocated to it.")
This document cannot be edited as it has a payment or credit note allocated to it
Error
The invoice has already been paid or partially paid in Xero, and it was then edited in splose.
How to fix it
Update the invoice directly in Xero, or delete the invoice in both splose and Xero and record the payment correctly on the first attempt.
The status VOIDED cannot be applied to the invoice because it has payments or credit notes allocated to it
Error
The invoice has a credit note allocated to it. Unlike a standard payment allocation, a credit note association permanently locks the invoice; it can't be edited or deleted even after the credit note has been voided and the invoice reverted to draft. The credit note must be archived in splose and voided in Xero before any further changes.
How to fix it
Go to Client Profile, then Statements, then Based on Activity, and locate the credit note.
Archive the credit note via Actions, then Archive in splose.
Void the same credit note in Xero (not synced; must be done in both).
Once the credit note is removed, void any payments on the invoice.
Revert the invoice to draft.
Delete the invoice.
⚠️ If payments are voided before the credit note is archived, the invoice may become stuck and unable to be deleted. If this happens, contact the splose support team.
Invoice status and lock dates
The invoice is still a draft and won't sync
Error
There's often no error message at all. The invoice simply doesn't appear in Xero. An invoice only syncs once it leaves Draft status.
How to fix it
Open the invoice and check its status.
If it's still Draft, email it or click Mark as sent so it moves to Awaiting Payment.
It will then sync to Xero.
The document date cannot be before the period lock date
Error
Your accounts (in your organisation's chart of accounts) or system accounts (set by Xero) are locked in Xero.
How to fix it
Lock dates are typically set by your accountant, so it's worth checking with them first. Otherwise, remove the lock dates in Xero, then re-sync the invoice. To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several.
The document date cannot be before the end of year lock date
Error
The lock date is set at the end of year lock date, and Xero won't allow you to add or edit invoices dated before it. Wording is usually:
"The document cannot be edited as it is currently dated before the end of year lock date, currently set at 30-Jun-2025."
How to fix it
In Xero, go to Advanced, then Financial settings, and adjust or remove the lock date, or change the invoice date in splose to a date after the lock date. Then re-sync the invoice. To re-sync, click Sync with Xero on the invoice, or go to the Xero integration page (Workspace Settings > Integrations, then Settings on the Xero tile) and use Sync Now for a single invoice or Sync Selected for several. (This is common around EOFY.)
Having trouble finding the invoice number in Xero?
The invoice in Xero may be voided or deleted. To check, go to Business, then Invoices and click the search button.
Select the Include deleted & voided checkbox and click Search.
You will see any voided and deleted invoices here.
Frequently Asked Questions
Why doesn't my item or product code appear on the invoice in Xero?
Why doesn't my item or product code appear on the invoice in Xero?
This is expected. Item and product codes are used inside splose, for invoices, reporting, and Medicare or NDIS claims, but they don't transfer to Xero when an invoice syncs. Xero invoices are used for reconciliation and accounting, so only the accounting-relevant fields carry across.
What syncs to Xero:
Invoice totals
Tax rates
Line item descriptions
The Xero account code assigned to each service or product
You don't need to recreate your item codes in Xero. Manage them in splose:
Product codes: open Products, then a product; the item code is in the product details.
Service codes: go to Settings > Services > Actions (three dots) > Edit.
Still failing? When to contact support
Some Xero sync failures aren't caused by settings you can change; they're backend or Xero-side faults. If you've followed the steps above and the invoice still won't sync, or you see any of the following, contact the splose support team so we can investigate:
"Error, an error occurred"/"Xero Sync Failed"/"Failed to sync… try again", with no further detail
"Xero authentication fails/error" (especially where one Xero organisation is shared across several splose workspaces)
"We could not find the organisation…" when reconnecting repeatedly fails
"Missing tenant ID", or the Connected-organisation dropdown won't open or save
504 Gateway Time-out/"upstream connect error… overflow"
Due dates shifting by a day, or tracking categories not applying at line-item level, when your settings are correct
A bulk/lump-sum payment across 200+ invoices that won't re-sync
When you contact us, include the exact error text and the invoice number(s) affected so we can resolve it faster.
📝 Want to learn more about our Xero integration? Visit our Xero integration page.