QuickBooks Grid Integration

The QuickBooks Grid integration enables finance, accounting, and sales operations teams to view, search, and export financial records from QuickBooks Online directly inside AppColab Grid without duplicating sensitive accounting data in Salesforce storage.

With the upgraded QuickBooks provider, teams can access 14 financial entities (including Invoices, Customers, Payments, Bills, Estimates, and Items), leverage dynamic SQL-based server pagination, and embed context-aware child grids on Salesforce Accounts and Contacts.

Architecture & What’s Deployed

One-Time Manual Setup (Permanent OAuth 2.0)

Setting up an OAuth 2.0 connection ensures Salesforce maintains a permanent, secure link to your QuickBooks Online company. Salesforce securely stores the refresh token and automatically refreshes short-lived access tokens in the background—eliminating manual token pasting entirely.

[!TIP] > Permanent Connection (Recommended): Use Salesforce Auth. Providers + External Credential (OAuth 2.0) to keep tokens refreshed automatically. Manual bearer tokens generated from the developer playground expire after 60 minutes.

1. Register App in Intuit Developer Portal

1. Log in to the Intuit Developer Portal and navigate to Dashboard.
2. Select your App (or click Create an app with the Accounting API).
3. Under Keys & OAuth, locate:
   • Client ID
   • Client Secret
   • Realm ID / Company ID (found under Dashboard or by opening Sandbox/Company switcher)
4. Leave this tab open—you will paste your Salesforce Callback URL here in Step 2.

2. Configure Salesforce Auth. Provider

To maintain a permanent connection without 60-minute token timeouts, configure a Salesforce Auth. Provider:

1. In Salesforce Setup, enter Auth. Providers in the Quick Find box and click New:
   • Provider Type: OpenIdConnect (or custom Intuit provider)
   • Name: QuickBooks_OAuth
   • URL Suffix: QuickBooks_OAuth
   • Consumer Key: Paste your Intuit Client ID from Step 1
   • Consumer Secret: Paste your Intuit Client Secret from Step 1
   • Authorize Endpoint URL: https://appcenter.intuit.com/connect/oauth2
   • Token Endpoint URL: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
   • Default Scopes: com.intuit.quickbooks.accounting
2. Click Save.
3. Scroll down and copy the generated Callback URL (e.g. https://yourdomain.my.salesforce.com/services/authcallback/QuickBooks_OAuth).
4. Back in the Intuit Developer Portal under Keys & OAuth → Redirect URIs, click Add URI, paste the Salesforce Callback URL, and click Save.

3. Configure Credentials in Salesforce Setup

3.1 Create the External Credential (OAuth 2.0)

1. Go to Setup → enter Named Credentials in Quick Find → select Named Credentials.
2. Click the External Credentials tab → click New:
   • Label: QuickBooks
   • Name: QuickBooks
   • Authentication Protocol: OAuth 2.0
   • Authentication Provider: Select QuickBooks_OAuth
   • Scope: com.intuit.quickbooks.accounting
   • Click Save.
3. In the Principals section, click New:
   • Parameter Name: ApiKey
   • Sequence: 1
   • Identity Type: Named Principal
   • Scope: com.intuit.quickbooks.accounting
   • Click Save.
4. In the Principals table, click the dropdown menu ▼ next to ApiKey → click Authenticate.
5. A popup opens to Intuit. Sign in with your Intuit developer/company credentials and select your QuickBooks company to approve access. The Principal status will change to Configured.

3.2 Create the Named Credential

1. Click the Named Credentials tab (next to External Credentials) → click New:
   • Label: QuickBooks
   • Name: QuickBooks
   • URL: https://quickbooks.api.intuit.com (or sandbox: https://sandbox-quickbooks.api.intuit.com)
   • External Credential: Select QuickBooks
   • Generate Authorization Header: Checked
   • Allow Formulas in HTTP Header: Checked
2. Click Save.

4. Assign Permission Set Access

1. In Salesforce Setup, enter Permission Sets in Quick Find.
2. Select Integration Admin (or QuickBooks_Integration / your custom admin permission set).
3. Click External Credential Principal Access → click Edit.
4. Add QuickBooks - ApiKey to Enabled External Credential Principals.
5. Click Save and verify the permission set is assigned to your active users.

Use Case 1: Embedded Child Grids on Accounts & Contacts

1. In Salesforce, open AppColab Grid app → Grid Definitions tab → click New Grid Definition.
2. Fill in:
   • Grid Settings Name: QuickBooks_Invoices_Grid
   • Grid Label: QuickBooks Invoices
   • Is Active?: Checked
   • Data Provider Class: QuickBooksGridDataProvider
   • Data Provider Configuration:

     {
       "realmId": "123456789012345",
       "resource": "invoices"
     }
     

     Tip: Replace "123456789012345" with your actual Intuit Realm ID / Company ID. Set "resource" to "customers", "payments", or "bills" to display different financial objects.

3. Click Save & Next → proceed to Preview.
4. Live invoices load with Invoice Number, Customer, Amount, Balance, Due Date, and Status!

A. Customer Invoices on an Account

• Grid Settings Name: QuickBooks_Account_Invoices
• Grid Label: Customer Invoices (QuickBooks)
• Description: Context-aware child grid embedded on the Account record page displaying all live QuickBooks Online invoices specifically issued to the current customer, eliminating swivel-chair lookups during account reviews and contract renewals.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "invoices",
    "parentMatchColumn": "CustomerRef",
    "parentMatchField": "QuickBooks_Customer_Id__c"
  }
  

• Dynamic Field Resolution: When the grid loads on an Account, it reads QuickBooks_Customer_Id__c from the record and appends WHERE CustomerRef = '<value>' to both the count and page queries.
• Standard Field Fallback: If you prefer not to create custom fields, map parentMatchField to standard AccountNumber ("parentMatchField": "AccountNumber").
• Zero Row Safety: If the Salesforce record has no customer ID, the grid safely renders 0 rows without throwing an error.

B. Filtering Open/Overdue Invoices (where clause)

• Grid Settings Name: QuickBooks_Account_Open_Invoices
• Grid Label: Outstanding Invoices (QuickBooks)
• Description: Filtered child grid on the Account record page highlighting outstanding and overdue invoices with an open balance (Balance > 0), giving collections and customer success teams immediate visibility into pending cash flow.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "invoices",
    "parentMatchColumn": "CustomerRef",
    "parentMatchField": "QuickBooks_Customer_Id__c",
    "where": "Balance > '0'"
  }
  

• The provider automatically joins custom predicates using AND (e.g. WHERE CustomerRef = '58' AND Balance > '0').

C. Customer Payments on an Account

• Grid Settings Name: QuickBooks_Account_Payments
• Grid Label: Customer Payments & Receipts (QuickBooks)
• Description: Context-aware child grid embedded on the Account record page displaying historical payments, wire transfers, and receipts applied to the current customer with real-time transaction amounts and payment method references.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "payments",
    "parentMatchColumn": "CustomerRef",
    "parentMatchField": "QuickBooks_Customer_Id__c"
  }
  

D. Vendor Bills on Accounts or Suppliers

• Grid Settings Name: QuickBooks_Account_Bills
• Grid Label: Vendor Bills (QuickBooks)
• Description: Embedded child grid on Account or Supplier record pages showing live vendor bills, open balances, and payment terms.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "bills",
    "parentMatchColumn": "VendorRef",
    "parentMatchField": "QuickBooks_Vendor_Id__c"
  }
  

Use Case 2: Standalone Management Grids

Create company-wide operational dashboards across your entire QuickBooks workspace.

1. Global Invoices & Receivables Ledger

• Grid Settings Name: QuickBooks_Invoices_Ledger
• Grid Label: Invoices & Accounts Receivable (QuickBooks)
• Description: Centralized accounts receivable ledger providing leadership, finance coordinators, and RevOps complete visibility into all issued, paid, and outstanding QuickBooks invoices with live search, server pagination, and CSV export.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "invoices"
  }
  

• High-volume ledger displaying invoice number, customer name, issue date, due date, total amount, and outstanding balance with server pagination and CSV export.

2. Centralized Customer Directory

• Grid Settings Name: QuickBooks_Customer_Directory
• Grid Label: Customer Directory & Balances (QuickBooks)
• Description: Searchable master directory of all QuickBooks customer accounts showing real-time outstanding balances, primary billing emails, phone numbers, and active account flags across the entire organization.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "customers"
  }
  

• Searchable directory showing customer names, billing emails, phone numbers, active status, and total outstanding balances.

3. Vendor Accounts Payable Ledger

• Grid Settings Name: QuickBooks_Vendor_Bills
• Grid Label: Vendor Bills & Accounts Payable (QuickBooks)
• Description: Organization-wide accounts payable ledger tracking vendor liabilities, supplier invoices, payment due dates, and open balances to streamline procurement oversight and cash management.
• Data Provider Configuration:

  {
    "realmId": "YOUR_COMPANY_ID",
    "resource": "bills"
  }
  

• Track accounts payable, open bills, vendor payment due dates, and outstanding liabilities across the organization.

Supported QuickBooks Entities (14 Total)

The QuickBooks provider accepts both singular and plural resource names:

Server-Side Pagination & Search Architecture

• SQL-Based Server Pagination: Queries QuickBooks using STARTPOSITION and MAXRESULTS. The provider only fetches the rows needed for the active page, supporting page sizes up to 1,000 and a default record limit of 1,000 (configurable up to 10,000).
• Multi-Page Server Search: When a user types a search term, the provider pages through QuickBooks records up to the configured limit, recalculates total matches, and updates the grid’s pagination controls dynamically.
• CSV Export: Users can export filtered views directly to CSV for executive reporting or reconciliation.

Troubleshooting & Common Gotchas

• 401 Unauthorized: Token expired:
  • Cause: If you configured the External Credential using a manual Custom Bearer header token from the Intuit OAuth Playground, that token expires after exactly 60 minutes.
  • Fix: Migrate to the OAuth 2.0 protocol with Salesforce Auth Provider (QuickBooks_OAuth) as shown in Step 2 & 3. Salesforce automatically refreshes expired access tokens in the background without user intervention.
• 400 Bad Request: Invalid Company ID / Fault: error:
  • Cause: The "realmId" in your Data Provider Configuration JSON does not match your active QuickBooks company ID, or the user who authenticated access belongs to a different company sandbox.
  • Fix: In Intuit Developer Portal, check your Company ID (Realm ID) and update the "realmId" property in the Grid Definition configuration JSON.
• 403 Forbidden / No Principal Access:
  • Cause: The logged-in Salesforce user does not have permission to access the QuickBooks - ApiKey external credential principal.
  • Fix: Ensure your permission set has QuickBooks - ApiKey enabled under External Credential Principal Access and is assigned to the user.
• Sandbox vs. Production URL Mismatch:
  • If your Intuit app is in Development / Sandbox mode, ensure your Named Credential URL is https://sandbox-quickbooks.api.intuit.com. If in Production, use https://quickbooks.api.intuit.com.