QuickBooks Connector
QuickBooks Connector
Breadcrumbs

Integration Failures

1.1 Record Stuck on "Awaiting Salesforce Sync"

Symptom: A Quickbooks_Customer__c (or other QB record) has Status__c = 'Awaiting Salesforce Sync' and the parent Salesforce record fields are not being updated.

Cause: The record was synced to QBO successfully but the trigger-based write-back to the parent Salesforce object failed. This is typically a field mapping issue.

Fix:

  1. Check Status_Description__c on the QB record — it will contain the specific field that could not be written (e.g., 'JSON error :: Cannot parse the field mapping json' or 'Field Mapping not found').

  2. Go to Admin Setup → Field Mapping and verify the reverse mapping (QBO→SF) is correctly configured for the parent object.

  3. Check that the mapped Salesforce fields are accessible to the running user (FLS).

1.2 "Company not found" on QB Records

Where it appears: Status_Description__c = 'BatchSFQBCustomerSync.execute Company not found'

Cause: The Quickbooks_Customer__c (or similar) record has a Quickbooks_Company__c lookup that points to a Quickbooks_Company__c record that either does not exist, is inactive (Active__c = false), or has not yet been connected.

Fix:

  1. Open the QB record → verify Quickbooks_Company__c is populated and points to an active, connected company.

  2. Go to Admin Setup and confirm the company's Status__c is Successfully Synced and Active__c = true.

  3. If the company record is missing, re-run the authorization flow to recreate it.

1.3 Duplicate Records Not Created (Upsert Logic)

Symptom: Running the QBO→SF sync appears to succeed but no new records are created in Salesforce, even for records that should be new.

Cause: All QBO→SF syncs use upsert on the Composite_Unique_Key__c field. The key format is: {QB_Id}::{EntityType}::{realmId} (e.g., "59::Customer::1185883450"). If a record already exists with the same key, it is updated, not inserted.

This is expected behaviour. It prevents duplicates across repeated sync runs.

When this is a problem: If you see the wrong data on an existing record, check the Composite_Unique_Key__c field on the QBO record in Salesforce — if it matches a different company's realm ID, a previous authorization may have merged data from two companies.

1.4 Webhook-Triggered Sync Not Firing

Symptom: A record is updated in QBO but the corresponding Salesforce QB record is not updated.

Cause options:

  1. The Ignore_Webhook__c flag is true on the record (set by the connector itself after an outbound sync to prevent loops).

  2. The webhook notification was delivered for an operation the handler does not process (Delete and Merge are not handled by Webhook_QBChangeHandler — only Create, Update, and Void).

  3. The QBO webhook is not configured or has expired in the Intuit Developer Portal.

Fix:

  1. For Ignore_Webhook__c: this flag resets to false automatically on the next save. If it is stuck, manually set it to false on the record.

  2. For unsupported operations: run the Sync from QuickBooks batch manually from the Admin Setup page.

  3. For webhook configuration: verify the endpoint https://your-org.my.salesforce.com/services/apexrest/getUpdatesQB/ is registered and active in the Intuit Developer Portal under Webhooks