If an invoice fails to sync to Xero, the issue is usually related to one of a few common causes such as disconnected integrations, archived contacts, invalid tax mappings, or invoices that can no longer be edited in Xero.
This guide explains the most common sync issues and how to resolve them.
Before You Start
Before troubleshooting further:
Confirm your Xero account is still connected
Open the invoice in Hoops and review any displayed sync error
Check the invoice Accounting Status
Try syncing the invoice again after resolving the issue
Most Common Fix: Disconnect and Reconnect Xero
The most common resolution for Xero sync issues is reconnecting the integration.
Go to:
Settings → Integrations
Disconnect the Xero integration, then reconnect it again by following the standard Xero connection workflow.
This refreshes the authentication and can resolve many temporary sync or permission issues.
Error: Customer Has Been Archived in Xero
This is one of the most common causes of invoice sync failures.
Why This Happens
The first time Hoops sends an invoice to Xero, Hoops either:
matches an existing Xero contact using the email address, or
creates a new contact in Xero automatically
Once this happens, both systems store a shared contact ID for future invoice syncing.
If that contact is later archived in Xero, Hoops will still attempt to send invoices to the original contact ID. Because the contact is archived, Xero rejects the invoice sync.
Many users search Xero for the email address, cannot find the contact, and assume the customer does not exist. However, the contact usually still exists underneath Xero as an archived contact.
Solution
Restore the archived contact in Xero.
Xero Help Guide:
https://central.xero.com/s/article/Archive-or-restore-contacts
After restoring the contact, try syncing the invoice again.
Error: Cannot read property 'hoopsTaxId' of null
Why This Happens
This error is usually caused by an incomplete or blank custom tax mapping in the Xero integration settings.
Hoops supports custom tax mappings between Hoops and Xero tax codes. If one of these mappings is left blank or incomplete, invoice syncing can fail.
Solution
Go to:
Settings → Integrations → Xero Settings
Review all configured tax mappings and ensure there are no blank or incomplete fields.
After correcting the mapping, try syncing the invoice again.
Invoice Cannot Be Updated Because It Has Payments Applied
If the invoice has already been partially paid or fully paid in Xero, Xero may prevent further edits to the invoice.
This commonly happens when:
pricing changes after payment
quantities are updated after reconciliation
line items are modified after payment allocation
Why This Happens
Xero protects accounting integrity by restricting edits to invoices with payments attached.
Because of this, Hoops cannot overwrite the invoice in Xero once payments are allocated.
Learn More
See:
Other Common Causes
Invalid or Archived Account Codes
If an account code configured in Hoops no longer exists in Xero, the invoice may fail to sync.
Review your Xero configuration settings and confirm all account codes are still active.
Tax Code Configuration Problems
Invalid or mismatched tax settings between Hoops and Xero can prevent syncing.
Review:
default tax settings
custom tax mappings
invoice tax configuration
Temporary Xero API or Connection Issues
Occasionally Xero may experience temporary API or authentication issues.
If everything appears configured correctly:
Wait a few minutes
Reconnect the integration
Retry the sync
Still Need Help?
If the invoice still will not sync:
take a screenshot of the error
include the invoice number & Hoops Job/SalesDoc number
confirm whether the invoice already exists in Xero
This helps our support team diagnose the issue much faster.