Troubleshoot Xero sync errors
When the Xero accounting integration fails, financial records may not transfer correctly from Zenoti to Xero. This guide covers the most common failure modes, how to resolve them, how to handle already-synced records, and how to reconcile the variance.
This article covers the Xero Cloud deployment only — Zenoti does not integrate with desktop or server-based Xero products.
On this page
- Before you begin
- Common Xero sync errors
- Step-by-step troubleshooting
- Unsynced vs synced records
- Refunds and reversals from both sides
- Reconciliation after a failure
- Prevent recurring Xero sync failures
- Related articles
Before you begin
Permission: Organization administrator access is required to troubleshoot accounting sync issues in Zenoti, plus Xero Standard access or higher to investigate on the Xero side.
- Your Xero connection must be authorised. See Connect an accounting provider.
- Data mapping must be configured. See Configure accounting data mapping.
Common Xero sync errors
| Failure mode | Likely cause | User-visible symptom | Resolution |
|---|---|---|---|
| Token expired | Xero OAuth refresh token has expired after 60 days of inactivity | "Token expired" or "Unauthorized" error on all records | Re-authorise from Configuration > Integrations > Integration settings, expand Accounting, open Authorize, and select Re-Authorize. Sign in to Xero. |
| Account mapping error | A Zenoti revenue category, payment agent, or tax code is not mapped to an active Xero account | "Account not found" or "Account inactive" on failed records | Review mapping. See Configure accounting data mapping. Confirm every target account is still active in Xero. |
| Currency mismatch | Zenoti transaction currency does not match Xero organisation's base currency or any enabled multi-currency | "Currency not supported" on affected invoices | Either align currencies (use the Xero base currency in the Zenoti center) or enable multi-currency in Xero and add the currency. |
| API rate limit exceeded | Too many requests to Xero in a short window (Xero enforces a daily quota per tenant) | Queued status in bulk; syncs resume next day | Wait for the rate limit to reset (resets daily at Xero's cycle). Reduce manual sync date ranges; spread historical backfills across days. |
| Validation error | Data sent violates a Xero business rule | "Validation error" with Xero-specific message | Read the message. Common cases: inactive account code, locked accounting period in Xero, invoice number exceeds Xero's character limit, missing required field. |
| Duplicate invoice | Invoice with the same reference already exists in Xero | "Duplicate invoice number" error | Check Xero for the duplicate. Void or delete it in Xero (if appropriate), then retry. Most duplicates are caused by manual entries in Xero that duplicate Zenoti syncs — stop entering those manually. |
| Tax rate not found | Zenoti tax group is mapped to a Xero tax rate that has been archived or deleted | "Tax rate not found" | Re-map to an active Xero tax rate via Configure Xero VAT mapping. |
| Sync stuck in Pending/Queued | Xero service temporarily unavailable or network blip | Records don't progress | Wait 15 minutes. Check status.xero.com. Queued records retry automatically. |
| Financial Lock mismatch | Financial Lock period at the organization level is different from the center level | Records appear eligible but are not picked up for sync | Verify Financial Lock dates at both levels match. Mismatched dates silently exclude records. |
| Period closed in Xero | Xero's lock date excludes the posting date | "Period is closed" | Either reopen the period in Xero (with finance sign-off) or move the sync start date and reconcile the gap manually. |
| Multi-currency invoice to single-currency org | Zenoti sends a foreign currency to a Xero org without multi-currency enabled | "Currency not supported" | Enable multi-currency on the Xero subscription or route the affected center to a Xero org that supports it. |
Step-by-step troubleshooting
- Navigate to Configuration > Integrations > Integration settings, then search and expand Accounting.
- Open the Sync Report or Activity Log.
- Filter for records with SyncFailed status.
- Click a failed record to view the error returned by Xero.
- Identify the error type in the table above and apply the corresponding resolution.
- After fixing the underlying issue, failed records are automatically retried in the next scheduled sync cycle. To retry immediately, run a manual sync for the affected date range.
Unsynced vs synced records
Troubleshooting depends on whether the record has reached Xero yet.
Unsynced record (Pending, Queued, SyncFailed)
The record lives only in Zenoti.
- You can edit or void the record in Zenoti normally.
- On the next sync cycle (or after a manual retry), Zenoti posts the corrected record.
- No cleanup is required in Xero because nothing was posted there.
Synced record (status is Synced; record exists in Xero)
Once the record is in Xero, Xero is the authoritative copy. Zenoti does not silently amend synced invoices because Xero's audit rules disallow in-place edits to posted records.
- Use void and reissue in Zenoti. This creates a compensating credit note in Xero and a new corrected invoice on the next sync.
- If the original posting date is inside a Xero accounting period that has been locked, the reversal posts to the current open period. Work with finance to ensure period locks align.
- Never delete the Xero-side invoice manually unless finance explicitly instructs it — manual deletes break the Zenoti reference and future retries will push a duplicate.
Refunds and reversals from both sides
| Dimension | Zenoti side | Xero side |
|---|---|---|
| Trigger | Front desk issues a refund on the Zenoti invoice | Zenoti posts a credit note (negative invoice) on the next Payment sync |
| Line items | Mirrors the original invoice | Xero credit note with the same line-level breakdown |
| Tax treatment | Follows the original tax group mapping | Xero applies the reverse of the original VAT/tax treatment |
| Bank effect | Zenoti does not see the bank settlement | Xero's clearing account shows the refund; bank reconciliation matches the processor's refund batch |
| Link to original | Zenoti invoice shows the refund inline | Credit note in Xero references the original invoice number in the reference field |
| Manual reconciliation | None on Zenoti | Xero usually auto-allocates, but finance should verify the credit note is applied against the original invoice |
If a refund sync fails, the record appears in the Zenoti sync report with a specific error. Most commonly: the original invoice has been voided or deleted in Xero; re-create or restore the original before retrying the refund sync.
Reconciliation after a failure
After resolving a batch of failures, reconcile to confirm the fix worked.
| Source | Where | What to check |
|---|---|---|
| Zenoti | Collections by Invoices report + Accounting variance report | Invoice totals by payment agent for the period |
| Xero | Business > Invoices filtered to the period | Invoice count and total by customer or tracking category |
| Match key | Zenoti invoice number, written to the Xero reference field | Every Zenoti invoice must appear in Xero with the same amount |
Reconcile at least weekly, and always before the Xero accounting period is locked. See the Accounting variance report for the variance workflow.
Prevent recurring Xero sync failures
- Re-authorise proactively. If your Xero connection has been idle for more than 60 days, re-authorise it before running a sync.
- Keep account codes active. Before archiving or deleting accounts in Xero, update the mapping in Zenoti first.
- Match currencies. If you add a new center operating in a different currency, configure the currency in Xero before enabling sync for that center.
- Align Financial Lock dates. Keep organisation-level and center-level dates in sync.
- Monitor sync health. Use the integration health dashboard to catch failures early.