QuickBooks Connector
QuickBooks Connector
Breadcrumbs

Login Issues

1.1 OAuth Authorization Window Does Not Open

Symptom: Clicking Connect to QuickBooks opens the QBAuthVFPage but the browser does not redirect to the QuickBooks login page.

Cause: The authURL constructed by QBAuthController is blank or invalid, which happens when Quickbooks_Credentials__c.State_URL__c is empty.

Fix:

  1. Go to Setup → Custom Settings → Quickbooks Credentials → Manage → Default.

  2. Confirm State_URL__c is populated (this is the Salesforce org URL used as the OAuth state parameter, e.g., https://your-org.lightning.force.com).

  3. Confirm BusinessOrg_Site in Quickbooks_Common_Settings__c is https://cloudmaveninc.my.salesforce-sites.com and BusinessOrg_Path is sms.

  4. If using Sandbox mode, confirm Sandbox_Client_ID__c and Sandbox_Client_Secret__c are populated; the connector uses these when ApiInstance = Sandbox.

1.2 "Issue in Authentication" After QBO Login

Symptom: User completes the QBO login but the page shows Authorization Failed.

Cause: The auth code exchange call to https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer failed. Common reasons:

  • redirect_uri in the token request does not exactly match the URI registered in the Intuit Developer Portal app settings.

  • Client ID or Client Secret is incorrect or belongs to the wrong environment (Production vs Sandbox).

  • The auth code was already used (each code is single-use with a 10-minute TTL).

Fix:

  1. Verify the Redirect URI in your Intuit Developer Portal app settings exactly matches: https://cloudmaveninc.my.salesforce-sites.com/sms/QB_AuthVFPage

  2. Confirm the correct Client_ID__c and Client_Secret__c (or their Sandbox equivalents) are saved in the Default Quickbooks Credentials record.

  3. Check ApiInstance in Quickbooks_Common_Settings__c — it must be Production if using production credentials, Sandbox if using sandbox credentials.

  4. If the page already showed an error once, click Connect to QuickBooks again to get a fresh auth code.

1.3 "Invalid characters in auth Code" / "Invalid characters in realmId"

Symptom: Authorization fails with the above message written to the QB_Auth__e platform event.

Cause: QBAuthController validates that both the authCode and realmId contain only alphanumeric characters, dashes (-), and underscores (_). Any other character causes immediate rejection.

Fix: This is a security validation. If you see this error in normal usage, it indicates the middleware relay is appending unexpected characters. Contact Cloud Maven support — the middleware QB_AuthVFPage on the business org may need to be checked.

1.4 Refresh Token Expiry / Tokens Stop Working After ~100 Days

Symptom: All sync operations suddenly fail with API authentication errors. The BatchRefreshTokenUpdate batch stops succeeding.

Cause: QBO refresh tokens have a maximum lifetime of 100 days. The BatchRefreshTokenUpdate batch refreshes them automatically every 24 hours (Refresh_Token_Last_Modified_Date__c.addHours(24) <= Datetime.now()). If the batch was not running for an extended period, the refresh token may have expired entirely.

Fix:

  1. Check the last successful run of BatchRefreshTokenUpdate in Setup → Apex Jobs.

  2. Ensure it is scheduled — it should run daily. If the schedule was removed, re-schedule it:

System.schedule('QB Refresh Token Update', '0 0 1 * * ?', new BatchRefreshTokenUpdate());

  1. If the refresh token has already expired (100+ days since last auth), the user must re-authorize from scratch via the Connect to QuickBooks button.