QuickBooks Connector
QuickBooks Connector
Breadcrumbs

Batch Failures

1.1 Batch Reference

The connector uses the following batch classes. All are findable in Setup → Apex Jobs.

Batch Class

Direction

Entity

BatchSFQBCustomerSync

SF → QBO

Customer (individual record sync)

BatchSFQBInvoiceSync

SF → QBO

Invoice

BatchSFQBProductSync

SF → QBO

Product / Item

BatchSFQBVendorSync

SF → QBO

Vendor

BatchAllQBSFCustomersSync

QBO → SF

All Customers (full pull)

BatchAllQBSFInvoiceSync

QBO → SF

All Invoices (full pull)

BatchAllQBSFAccountsSync

QBO → SF

All Accounts (full pull)

BatchAllQBSFPaymentSync

QBO → SF

All Payments (full pull)

BatchAllQBSFProductsSync

QBO → SF

All Products (full pull)

BatchAllQBSFVendorsSync

QBO → SF

All Vendors (full pull)

BatchQBSFCustomerWebhook

QBO → SF

Customer (webhook-triggered)

BatchQBSFInvoiceWebhook

QBO → SF

Invoice (webhook-triggered)

BatchQBSFAccountWebhook

QBO → SF

Account (webhook-triggered)

BatchQBSFProductWebhook

QBO → SF

Product (webhook-triggered)

BatchQBSFPaymentWebhook

QBO → SF

Payment (webhook-triggered)

BatchQBSFVendorWebhook

QBO → SF

Vendor (webhook-triggered)

BatchRefreshTokenUpdate

Internal

Refresh Token Rotation

BatchAutoMatchQBCustomers

Internal

Auto-match QBO customers to SF records

BatchQBClassSync

QBO → SF

QBO Classes

BatchQBTaxRateSync

QBO → SF

Tax Rates

1.2 Batch Does Not Start / Stays in "Queued" State

Cause: Each batch class has a duplicate-run guard — if an instance of the same batch is already Processing, a new invocation immediately returns an empty scope and does nothing. This prevents concurrent runs against the QBO API rate limit.

Fix:

  1. Go to Setup → Apex Jobs and find any Processing instance of the batch.

  2. If it is genuinely stuck (running for more than 30 minutes with no progress), click Abort on the stuck job.

  3. Then re-trigger the batch from the Admin Setup UI or via Anonymous Apex.

1.3 SF → QBO Batch Records Stuck in "Failed"

Symptom: Quickbooks_Customer__c (or other) records have Status__c = 'Failed' and Process_via_Batch__c = false.

Cause: The batch sets Process_via_Batch__c = false after any failure so the record is not retried automatically. The AcceptedStatusFields common setting controls which statuses are eligible for batch pickup — by default this is 'Awaiting Salesforce Sync,Failed'.

Fix:

  1. Read Status_Description__c to identify the root cause.

  2. Fix the underlying issue (credentials, company, field mapping).

  3. Set Process_via_Batch__c = true and Status__c = 'Failed' on the affected records to re-queue them (the AcceptedStatusFields setting includes Failed by default, so they will be picked up on the next batch run).

  4. Alternatively, use the Retry button in the QuickBooks UI if available for the record type.

1.4 QBO → SF Full Pull Batch Pulling Wrong Records

Cause: Each BatchAllQB* class supports a custom WHERE clause stored in CM_QB_Connector_Settings__mdt metadata. For example, BatchAllQBSFCustomerSync_WhereClause filters which QBO customers are pulled. If this is misconfigured, it may exclude records you expect.

Fix:

  1. Go to Setup → Custom Metadata Types → CM QB Connector Settings.

  2. Find the record named BatchAllQBSFCustomerSync_WhereClause (or the relevant entity variant).

  3. Confirm the Value__c field contains a valid QBO WHERE clause (e.g., WHERE Active = true) or is blank to pull all records.

1.5 Last Sync Config Not Updating

Symptom: The Last_Sync_Config__c JSON field on Quickbooks_Company__c does not reflect the latest sync date/status.

Cause: Last_Sync_Config__c is only updated in the finish() method of the full-pull batches (BatchAllQBSFCustomersSync, BatchAllQBSFInvoiceSync, etc.), not the individual SF→QBO sync batches. If the finish() method throws an exception, the config is not written.

Fix: Check the debug log for the finish() execution of the relevant batch in Setup → Apex Jobs → [Job ID] → View Debug Log.