Documentation

QuickBooks Online Sync — Setup Guide

Sync your Salesforce customers, products, and invoices to QuickBooks Online — and see payment status flow back automatically.

On this page ▾

Before you start1 · Permission sets2 · Intuit app 3 · Connect4 · Connection record5 · Test 6 · Default profiles7 · Income account8 · Prepare data 9 · First sync10 · Reconciliation11 · Invoice buttonValidation rules MonitoringTroubleshootingGoing liveSupport

✦Before you start — is this connector right for you?

1Assign permission sets

The package ships three permission sets. Assign based on role:

Setup → Permission Sets → select each → Manage Assignments → Add Assignment.

2Create your QuickBooks (Intuit) app

You connect Salesforce to QuickBooks with your own Intuit app. (Each company uses its own, so your credentials are never shared.)

1. Go to developer.intuit.com → sign in → Dashboard → Create an app.
2. Choose QuickBooks Online and Payments, scope com.intuit.quickbooks.accounting.
3. Open Keys & credentials. Use the Development keys for your dry run; switch to Production keys when you go live. Copy the Client ID and Client Secret.
4. Under Redirect URIs, add exactly (replace MyDomain with your Salesforce My Domain):

   https://MyDomain.my.salesforce.com/services/authcallback/QuickBooks

   No trailing slash. This must match Step 3 character-for-character, or authorization fails with invalid_redirect_uri.

3Connect Salesforce to QuickBooks

3a · Auth Provider

Setup → Auth. Providers → New → Type: OpenID Connect (or use the packaged QuickBooks Auth Provider if present and just fill in the keys):

Enable Use PKCE (recommended by Intuit). Save.

3b · Confirm the callback URL

After saving, the Auth Provider shows a Callback URL. Confirm it matches what you registered in Step 2. If different, correct the Intuit Redirect URI to match.

3c · External Credential + Named Credential

The package provides QuickBooks Online External and Named Credentials (or create them):

• External Credential QuickBooks_Online — Authentication Protocol OAuth 2.0, Named Principal, referencing the QuickBooks Auth Provider above.
• Named Credential QuickBooks_Online — URL:
  • Sandbox: https://sandbox-quickbooks.api.intuit.com
  • Production: https://quickbooks.api.intuit.com

3d · Authorize

On the External Credential → Principals → the named principal → dropdown → Authenticate. Sign in to QuickBooks, choose your company, approve the scopes. Status should read Authenticated.

3e · Grant the principal

On both Integration OS Admin and Integration OS User permission sets, confirm the External Credential Principal Access for QuickBooks_Online is enabled. (The packaged sets already include this.)

4Create the connection record

Open the Integration OS Admin Console (App Launcher → Admin Console) → Connections, or create an External System record:

The last two fields enforce the USD / US-only boundary.

5Test the connection

In the console, Connections → Test connection (or Test Connection on the record).

6Install the default sync profiles

Rather than building sync configuration by hand, install the shipped defaults. Console → Connections → your connection → Install QuickBooks defaults. This creates four inactive sync profiles:

7Point the Item profile at your income account

This is the one value the connector can't guess — your chart of accounts is unique to your company.

1. Sync your chart of accounts: the console has a Chart of Accounts reference pull, or run the QuickBooks Chart of Accounts → External Reference profile once. Your accounts appear as External Reference records.
2. On the Product2 → QuickBooks Item profile, open the IncomeAccountRef.value field mapping → set Reference Value to the income account you want (e.g. Sales of Product Income), chosen from the synced list.

8Prepare your data (external Id fields)

The connector tracks what's synced using QBO_* Id fields on your records (populated automatically on first sync): Account.QBO_Customer_Id__c, Product2.QBO_Item_Id__c, Opportunity.QBO_Invoice_Id__c.

Ordering matters — an invoice needs its customer and items to exist in QuickBooks first:

1. Sync Customers (Accounts)
2. Sync Items (Products)
3. Sync Invoices (Opportunities)

Add a Record Filter to each outbound profile to limit which records sync (e.g. only Opportunities in a certain stage). Without a filter, every record of that object is a candidate.

9Activate and run your first sync

1. Console → Sync Profiles → activate Account → QuickBooks Customer (toggle Activate).
2. Click Run now. Watch the Logs tab — you should see records created with a QuickBooks Id written back.
3. Repeat for Item, then Invoice, in that order.

Start with a Record Filter that matches only a handful of records for the very first run, confirm they look right in QuickBooks, then widen it.

10Turn on automatic payment reconciliation

So paid invoices update in Salesforce without anyone clicking:

1. Console → Sync Profiles → QuickBooks Invoice → Opportunity (Payment Reconciliation).
2. Set Trigger Type = Scheduled, Interval = Hourly (or as you prefer). Activate.
3. Confirm the background jobs are running: the console Diagnostics tab shows "Sync dispatcher scheduled." If it says the dispatcher isn't scheduled, an admin registers them once:

Setup → Developer Console → Debug → Open Execute Anonymous Window
integos.IOS_InstallHandler.scheduleAll();

This one-time step schedules the dispatcher, health monitor, and log-retention jobs. Re-running it is safe — it never duplicates jobs.

Once running, each Opportunity's QBO Payment Status (Paid / Partially Paid / Open) and QBO Balance update automatically from QuickBooks.

11The "Generate QuickBooks Invoice" button

For on-demand invoicing from a single Opportunity:

1. Add the Generate QuickBooks Invoice action to your Opportunity page layout (Setup → Object Manager → Opportunity → Page Layouts → Mobile & Lightning Actions).
2. On any Opportunity, click it. The connector checks it isn't already invoiced, then sends it. The QBO Invoice No. field populates within moments.

---

§Validation rules & the integration user

When data flows into Salesforce (for example, payment reconciliation), the connector performs standard DML — so your org's validation rules, required fields, Apex triggers, flows, and duplicate rules all run. They are never bypassed by default. A record that fails a rule fails on its own, with the exact rule message written to the sync log; every other record in the batch still syncs.

If a specific rule shouldn't apply to synced writes, exempt it deliberately using the shipped opt-in permission:

1. Pick the integration user that runs your syncs. Scheduled syncs run as the user who scheduled them — so run integos.IOS_InstallHandler.scheduleAll(); and activate profiles as that user (a dedicated integration user is cleanest).
2. Assign that user the Integration OS - Bypass Validation permission set — in addition to Integration OS Admin and QuickBooks Integration. It is a separate set on purpose, so nobody bypasses rules by accident.
3. Edit only the validation rules you want the sync to skip and add the permission check to the rule formula:

AND(
  NOT($Permission.integos__IOS_Bypass_Validation),
  /* ...your existing rule logic... */
)

Now that integration user's syncs skip exactly those rules, while every other user — and every rule you didn't touch — stays fully validated.

---

◎Monitoring — the Admin Console

App Launcher → Integration OS Admin Console:

• Overview — success rate, records synced, failures, connection health at a glance
• Diagnostics — active checks for silent problems: unscheduled jobs, duplicate profiles, missing filters, unhealthy connections. Check this first if something seems off.
• Connections / Sync Profiles / Logs — full detail; filter logs to Failed to triage

⚙Troubleshooting

▲Going live (from sandbox to production)

1. Swap the Auth Provider keys to your Production Intuit keys.
2. Change the Named Credential URL to https://quickbooks.api.intuit.com.
3. Add the production Redirect URI to your Intuit app; re-authenticate (Step 3d) against your real company.
4. Update the connection's Company / Realm Id to your production company.
5. Re-run Test connection — expect Healthy.
6. Do a small, filtered first sync in production before widening.

?Support

• Diagnostics tab first — it catches most setup issues automatically.
• Logs tab, filtered to Failed, shows the exact QuickBooks error per record.
• Still stuck? Email support@sfbro.com with your org Id, the profile name, and the failed log entry.
• Keep your Intuit Client Secret private; rotate it from the Intuit dashboard if exposed.