A broken Salesforce QuickBooks sync can duplicate customers, omit invoices or post revenue to the wrong account. Troubleshooting should begin with the data path and system ownership—not repeated retries. Identify exactly which record failed, at which step, under which rule and with what accounting consequence.
Define the integration contract
Document which system owns each field and event. For example, Salesforce may own opportunity and customer-facing sales data, while QuickBooks owns accounts, posted invoices, payments and the general ledger. Write the trigger, direction, frequency, identifier, mapping, approval and error-handling rule for each object.
| Object | Typical owner | Key control |
|---|---|---|
| Customer | Defined master system | Stable external ID |
| Product/service | Accounting or catalog owner | Mapped income and tax code |
| Invoice | QuickBooks after approval | Idempotent creation rule |
| Payment | Accounting/payment source | Do not infer from opportunity stage |
Classify the failure
Capture the record ID, timestamp, connector job, error message, user and recent configuration changes. Common classes include expired authorization, missing permissions, required fields, invalid references, incompatible data types, closed accounting periods, tax or currency mismatch, rate limits and connector outage.
Do not edit production records until the original payload and error are preserved. An error like “invalid account reference” needs a mapping correction; retrying the same payload only creates noise.
Prevent duplicates before replay
Use an immutable cross-system ID, not a company name or email alone. Verify whether the target record was created even if the connector reported a timeout. The operation should be idempotent: processing the same approved event twice must not create two invoices.
Export the affected set, choose a surviving master record and merge only after reviewing transactions, contacts, tax status and references. Back up data and test the merge in a sandbox when available.
Reconcile accounting outcomes
After reprocessing, compare record counts and control totals by date, entity, currency and document status. Trace a sample from opportunity or order to customer, invoice, payment and general-ledger posting. Confirm tax, discounts, classes or locations, deferred revenue and rounding. Our critical reconciliation guide provides a control-oriented method.
Safe recovery sequence
- Pause the failing flow if it can create bad records.
- Preserve logs and define the exact affected population.
- Correct authorization, configuration, mapping or source data.
- Test representative cases in a nonproduction environment.
- Backfill in small, uniquely identified batches.
- Reconcile totals and review exceptions.
- Monitor the next normal run and document the fix.
Frequently asked questions
Why does a sync create duplicate customers?
The connector may lack a stable external ID, match on changing text, or retry after a timeout without checking whether the first request succeeded.
Should failed invoices be deleted and recreated?
Not automatically. Preserve audit history, assess downstream effects and follow the accounting system’s supported correction process. Voiding or adjustment may be safer than deletion.
How should integration health be monitored?
Track failed and delayed jobs, queue age, duplicate warnings, unmatched identifiers, control-total differences and time to resolution, with a named owner.
Sources reviewed
- Salesforce REST API Developer Guide
- Intuit QuickBooks Online API documentation
- COSO Internal Control framework
Last reviewed: August 15, 2026.