ZenotiHelp

Troubleshoot QuickBooks Online sync errors

ZTZenoti Docs Team Updated September 3, 2026 5 min readGuide

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

Permission: Organization administrator access is required in Zenoti. You also need Company Admin access in QBO to investigate provider-side issues.


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

  1. Navigate to Configuration > Integrations > Integration settings, then search and expand Accounting.
  2. Open the Sync Report or Activity Log.
  3. Filter for records with SyncFailed status.
  4. Click a failed record to view the error details.
  5. Identify the error type in the table above and apply the corresponding resolution.
  6. 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.

  1. Navigate to Configuration > Business details > Business setup > Financials.
  2. At the organization scope, note the Lock financial data date.
  3. Set the scope selector to the center experiencing sync issues.
  4. Check the center's Lock financial data date.
  5. 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.

Was this article helpful?
Your feedback helps us improve our documentation.