Q: Why is my QBO record showing "Awaiting Salesforce Sync" forever? The record reached QBO successfully but the trigger-based reverse sync (QBO record → parent SF record) is waiting. Check Status_Description__c — if it says 'Field Mapping not found', configure the reverse field mapping in Admin Setup. If it says 'JSON error :: Cannot parse the field mapping json', the field mapping JSON stored in Custom_Field_Mapping__c is malformed and needs to be reconfigured.
Q: I re-authorized QuickBooks but old company records are still showing. Re-authorization creates a new Quickbooks_Credentials__c record keyed by the realmId and a new/updated Quickbooks_Company__c record. Old records are not deleted. Go to Admin Setup → Companies and deactivate (Active__c = false) any stale company records that no longer apply.
Q: Can I run two full-pull syncs for different companies at the same time? Yes. Each batch class checks for duplicate runs using the Apex class name — not the company ID — so technically two instances of BatchAllQBSFCustomersSync for different companies would block each other. Run them sequentially: wait for the first to finish (check Last_Sync_Config__c.Customer.status = 'Completed' on the first company) before starting the second.
Q: The "Connect to QuickBooks" window opens and then immediately closes. The QBAuthVFPage auto-closes after 2.5 seconds when the redirected flag is true. If it closes immediately without showing a success/failure message, the page loaded into the isRedirected = false branch (the outbound redirect) but the redirect itself failed silently. Check the browser console for JavaScript errors — the redirect is done via window.location.href = authUrl. If authUrl is blank, the Default credential's State_URL__c is missing.
Q: After a successful sync, why are some fields on the parent Salesforce record not updated? The QBO→SF field write-back is driven by the reverse field mapping in Custom_Field_Mapping__c. Only fields that appear in the mapping JSON are written back. If a field is not updating, open Admin Setup → Field Mapping → check the reverse mapping for the relevant object and ensure the target Salesforce field is included and the running user has FLS edit access to it.
Q: How do I check if the token refresh batch is healthy? Run this in Anonymous Apex:
List<AsyncApexJob> jobs = [
SELECT Id, Status, CompletedDate, NumberOfErrors
FROM AsyncApexJob
WHERE ApexClass.Name = 'BatchRefreshTokenUpdate'
ORDER BY CreatedDate DESC
LIMIT 5
];
System.debug(jobs);
The most recent job should have Status = 'Completed' and NumberOfErrors = 0. If CompletedDate is more than 26 hours ago, the scheduler may have been removed — re-schedule it as shown in Section 2.4.
Q: A sync failed with error code 5010 "Stale Object". What does SyncToken mean? Every QBO entity has a SyncToken — an integer that increments each time the record is modified in QBO. When the connector updates a record, it must send the current SyncToken. If someone else (or another integration) updated the record between the connector's last read and its update attempt, the SyncToken no longer matches and QBO rejects the update with error 5010. The fix is to refresh the record from QBO first (which updates Quickbooks_SyncToken__c in Salesforce), then retry the update.