Troubleshoot QuickBooks Online sync errors
When the QuickBooks Online (QBO) integration fails, records may not transfer correctly from Zenoti to QBO. This guide covers common failure modes, how to resolve them, how to handle already-synced records, and how to reconcile the variance.
This article covers QuickBooks Online only — Zenoti does not integrate with QuickBooks Desktop.
On this page
- Before you begin
- Common QBO sync errors
- Step-by-step troubleshooting
- Verify Financial Lock alignment
- Unsynced vs synced records
- Refunds and reversals from both sides
- Reconciliation after a failure
- Prevent recurring QBO sync failures
- Related articles
Before you begin
Permission: Organization administrator access is required in Zenoti. You also need Company Admin access in QBO to investigate provider-side issues.
- Your QBO connection must be authorised. See Connect an accounting provider.
- Data mapping must be configured. See Configure accounting data mapping.
Common QBO sync errors
| Failure mode | Likely cause | User-visible symptom | Resolution |
|---|---|---|---|
| Sync fails silently with no error | Financial lock period at the organization level does not match the center level | No records appear in the sync report even though transactions occurred | Navigate to Configuration > Business details > Business setup > Financials and align the Lock financial data date at both organization and center scopes. |
| Authorization expired | QBO OAuth token has expired | "Authorization expired" error on all records | Re-authorise from Configuration > Integrations > Integration settings, expand Accounting, open Authorize, and select Re-Authorize. Sign in to QBO as Company Admin. |
| Duplicate entry | A record with the same reference already exists in QBO | "Duplicate entry" error | Check QBO for the duplicate. Remove or void the duplicate (if appropriate) and retry. Most commonly caused by manual QBO entries that duplicate Zenoti syncs — stop entering those manually. |
| Records sync with incorrect amounts | Chart of accounts mapping is incomplete or points to the wrong accounts | Amounts in QBO differ from Zenoti | Review account mapping in Configure accounting data mapping. Verify every revenue category, tax code, and payment agent maps to the correct QBO account. |
| Tax amounts do not match | Tax rate mapping between Zenoti and QBO is misaligned, or inclusive vs exclusive pricing differs | Tax values in QBO differ from Zenoti | Verify each Zenoti tax group maps to the right QBO tax code. Check for rounding caused by tax-inclusive vs tax-exclusive pricing differences. Align with finance. |
| Business validation error | Data sent violates a QBO business rule | "Business validation error" with QBO-specific message | Read the message. Common cases: inactive account, closed accounting period in QBO, required fields missing, tax agency not configured. |
| Sync stuck in Queued | QBO rate limit reached or QBO service temporarily unavailable | Records stay in Queued | Wait 15 minutes. Check status.developer.intuit.com. Queued records retry automatically on the next sync cycle. |
| Inventory data not syncing | Inventory sync type not enabled in the sync schedule | No inventory records appear in QBO | Enable Inventory under sync schedules. See Configure accounting sync schedules. |
| Location or Class required but missing | QBO organisation has mandatory Locations / Classes but Zenoti center is unmapped | "Location required" or "Class required" | Map every Zenoti center to a QBO Location or Class in Configure accounting data mapping. |
| Period closed in QBO | QBO closing date excludes the posting date | "Period closed" error | Move the QBO closing date or reroute the posting to an open period through a manual reconciling entry. Agree cadence with finance. |
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 details.
- Identify the error type in the table above and apply the corresponding resolution.
- After fixing the issue, failed records are automatically retried in the next scheduled sync cycle. To retry immediately, run a manual sync for the affected date range.
Verify financial lock alignment
The most common cause of silent sync failures is a financial lock mismatch.
- Navigate to Configuration > Business details > Business setup > Financials.
- At the organization scope, note the Lock financial data date.
- Set the scope selector to the center experiencing sync issues.
- Check the center's Lock financial data date.
- Ensure both dates are aligned.
Important: When the financial lock period at the organization level does not match the center level, QBO sync may fail without displaying an explicit error message. Always check this setting first when diagnosing sync issues.
The center-level setting appears only after financial lock is enabled for the organization. If you do not see Lock financial data at the center scope, enable it at the organization scope first.
Unsynced vs synced records
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 required in QBO because nothing was posted there.
Synced record (status is Synced; record exists in QBO)
QBO becomes the authoritative copy. Zenoti does not silently amend synced invoices.
- Use void and reissue in Zenoti. Zenoti posts a credit memo (or voided invoice, depending on QBO state) as the reversal on the next sync, then posts the corrected invoice.
- If the original posting date is in a closed QBO period, the reversal posts to the current open period.
- Never delete the QBO invoice manually without finance approval — doing so breaks the Zenoti reference and can cause duplicate pushes on retry.
Refunds and reversals from both sides
| Dimension | Zenoti side | QBO side |
|---|---|---|
| Trigger | Front desk issues a refund on the Zenoti invoice | Zenoti posts a refund receipt (or credit memo) on the next Payment sync |
| Line items | Mirrors the original invoice | QBO refund receipt with the same breakdown |
| Tax treatment | Follows the original tax mapping | QBO reverses the original tax amount on the same agency |
| Bank effect | Zenoti does not see the bank settlement | QBO's clearing / bank account shows the refund after the processor settles |
| Link to original invoice | Zenoti invoice shows the refund inline | QBO sometimes auto-links; manual review is often required to apply the refund receipt to the original invoice |
| Manual reconciliation | None in Zenoti | Finance should verify refunds are applied against the correct invoice at month-end |
If a refund sync fails with "Original transaction not found," confirm the original invoice still exists in QBO and has not been manually voided or deleted.
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 |
| QBO | Sales > Invoices filtered to the period | Invoice count and total by customer, Location, or Class |
| Match key | Zenoti invoice number, written to the QBO reference field | Every Zenoti invoice must appear in QBO with the same amount |
Run this reconciliation at least weekly, and always before the QBO accounting period is closed. See the Accounting variance report for the variance workflow.
Prevent recurring QBO sync failures
- Re-authorise proactively. If your QBO connection sees long idle periods, re-authorise before running a sync.
- Keep account codes active. Update Zenoti mapping before archiving or deleting accounts in QBO.
- Align Financial Lock. Keep organisation-level and center-level dates aligned.
- Enforce Location or Class usage consistently if QBO requires them — partial enforcement causes intermittent failures.
- Monitor sync health. Use the integration health dashboard to catch failures early.