Sync QuickBooks and Salesforce

Companies wanting to supercharge their Salesforce implementation look to integrate data from third-party systems like QuickBooks. In the past, this has been cumbersome, and expensive. In part, because every company's Salesforce has slightly different configurations, and in part, because most QuickBooks packages put you in a box and are not configurable. With QIME (QuickBooks Integrations Made Easy), seamless QuickBooks integrations have arrived to the Salesforce ecosystem. QIME is the culmination of 5 years of custom QuickBooks integrations, distilled into a free, open-source package that is usable for the Salesforce community. QIME allows businesses to sync invoices, customers, and payments between the two systems. Below are the two most-common use cases that QIME solves.

Why Integrate Salesforce And QuickBooks Online?

Frequently, companies want to use their opportunities with opportunity products and push this information as an invoice to QuickBooks. With QIME, this is the primary use case. QIME was made in mind so that companies can seamlessly push their Sales data directly to QuickBooks, and collect payments on the invoices. Additionally, payments and balance dues are all tied to individual customers, so the power of Salesforce reporting can be leveraged to make pipeline reports, financial decisions, and more.

Before We Get Started

If you resonated with either of these use cases, QIME can be used to integrate your QuickBooks and Salesforce data. Let's discuss how to configure QIME in your Salesforce instance. Keep in mind that it is considered "Best-Practice" to configure this package in a sandbox first to see how your data and business process will integrate with the package.

To follow the latest developments with QIME, check out the GitHub repository. Additionally, if you need assistance with implementing QIME, and all things Salesforce, reach out to us here.

Requirements

The following software editions and permissions are required to configure QIME:

• Salesforce Enterprise Edition
• Salesforce Administrator Profile
• QuickBooks Online Essentials
• QuickBooks Online Administrator User

QIME Package Links

Sign up here to get the latest package versions.

QuickBooks Authentication

To set up the authentication for QBO, perform the following:

1. Navigate to QBO to sign in as a developer.
2. Go to Dashboard -> Create an app
3. Give the app a name like QIME or Salesforce
4. Use the scope com.intuit.quickbooks.accounting

If the QuickBooks environment is a sandbox, proceed with using the Development settings.

If this is a production environment, a few things will need to be completed to get the api credentials. This includes:

• Verifying your email
• Completing the app assessment questionnaire

Once this has been completed, go to the Keys & Credentials. This section will be used to store information and configure items within Salesforce.

Getting the Company Id

The easiest way to get the company id (realm id) for a QuickBooks Online company, perform the following:

1. Go to API Docs & Tools -> API Explorer
2. Scroll down to a request like Query an account
3. On the right side, there is a section with a url. The number in pink after /v3/company/ is the company Id.

Authentication In Salesforce

Auth. Providers

Go to Setup -> Auth. Providers and create a new Auth. Provider with the following configuration:

• Provider Type: QBAuthProvider
• Name: QB Auth Provider
• URL Suffix: QB_Auth_Provider
• Auth URL: https://appcenter.intuit.com/connect/oauth2
• Token URL: https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer
• Scope: com.intuit.quickbooks.accounting
• Realm Id: The company Id copied previously
• Minorversion: 65
• Execute Registration As: Any Admin User

At the bottom of the page, there are links to initialize and test the Auth. Provider. Take the Callback URL in the Salesforce Configuration section, and copy it into the Callback URL in the Auth. Provider Detail section.

Additionally, in the QuickBooks App, add the Callback URL as a redirect URI.

To test that the configuration is setup correctly, in the Auth. Provider page, open the Test-Only Initialization URL in a new tab, and sign into the desired QuickBooks account. If everything is configured correctly, you should be greeted with a page full of data in an xml format.

Named Credential

Within the Winter '23 Salesforce release, named credentials were upgraded with more features. One of these features includes selecting which users can run the named credential. This Salesforce component simplifies the connection between external, third-party services like QuickBooks, and allows the apex code to easily callout and update the necessary authentication details.

To configure the Named credential, go to Setup -> Named Credentials and go to the External Credentials tab. From here, create a new record with the following properties:

• Label: QB External Credential
• Name: QB External Credential
• Authentication Protocol: OAuth 2.0
• Authentication Flow Type: Browser Flow
• Authentication Provider: QBAuthProvider

From here, we can map the permissions to allow or restrict users to run the QuickBooks code. To configure for all users, create a new Permission Set Mapping with the following properties:

• Permission Set: QBO User
• Sequence Number: 1
• Identity Type: Named Principal

Next, the named credential needs to be created, which is the middleware that allows the apex code to access the authorization to QuickBooks. To configure this, go back to the Named Credential tab and create a new record with the following properties:

• Label: QB Named Credential
• Name: QB_Named_Credential
• URL: https://quickbooks.api.intuit.com *
• External Credential: QB External Credential
• Generate Authorization Header: False
• Allow Formulas in HTTP Header: True
• Allowed Namespaces: QIME

* If using a QuickBooks sandbox environment, user the following URL: https://sandbox-quickbooks.api.intuit.com

With this, all the configuration is done to authenticate with QuickBooks! All that needs to be performed is to authenticate with QuickBooks. To perform this, go to the QB External Credential, and scroll to the Permission Set Mappings, and under the Actions column for the QBO User permission set mapping, click the arrow to see more options, and press Authenticate. This will initiate the authentication flow, and store the credentials securely within Salesforce.

We're now ready to start syncing QuickBooks data with Salesforce. There are two important things to be mindful of with the authentication flow.

1. Only the first company can be configured per QuickBooks accounts. This means that if there is a sandbox account tied to the developer account, this will need to be deleted. Additionally, if multiple QuickBooks companies are tied to the same email address, only the first company is used.
2. The named credential flow uses a process called OAuth 2.0 to securely authenticate between Salesforce and QuickBooks. This does not store the username and password of the user that authenticates to QuickBooks, but a token that verifies the authenticity of the connection. This token will rotate, or change, hourly, so it is important to make callouts every hour to prevent the token from expiring. If the token expires, just perform the authentication step above to login and get a new token.

Syncing Customers

One of the objects that is essential to be linked is the Customer object in QuickBooks. All accounting entities within QuickBooks are linked to customers. This means that accounts in Salesforce need to be linked to customers in QuickBooks. Most implementations will need to account for creating new customers, and syncing existing customers to accounts.

Creating New Customers from Accounts

If you are starting with a fresh account, and the customer does not exist inside of QuickBooks, this is the easiest path to push data. There is an action to create new customers in QB from Salesforce accounts. To add this to the page layout:

1. Go to Setup → Object Manager
2. Navigate to Account
3. Select Page Layouts and open the desired page layout
4. In the Mobile & Lightning Actions find the Sync w/ QB action and add this to the actions section.

From here, just press Sync w/ QB on any account that needs to be pushed to QuickBooks.

To see how your Salesforce fields are mapped to QuickBooks Customers, please view the mapping table below

QuickBooks Field	Salesforce Label	Salesforce API Name
Active	True*	True
Billing Address Line 1	Billing Street	BillingStreet
Billing Address City	Billing City	BillingCity
Billing CountrySubDivisionCode	Billing State	BillingState
Billing Country	Billing Country	BillingCountry
Billing PostalCode	Billing PostalCode	BillingPostalCode
CompanyName	Account Name	Name
DisplayName	Account Name	Name
FreeFormNumber	Phone	Phone
IsProject	False*	False
Id	QB Id	qime__QB_ID__c
Job	False*	False
PrintOnCheckName	Account Name	Name
ResaleNum	Resale Number	qime__Resale_Number__c
SyncToken	SyncToken	qime__QB_SyncToken__c
Shipping Address Line 1	Shipping Street	ShippingStreet
Shipping Address City	Shipping City	ShippingCity
Shipping CountrySubDivisionCode	Shipping State	ShippingState
Shipping Country	Shipping Country	ShippingCountry
Shipping PostalCode	Shipping PostalCode	ShippingPostalCode
Taxable	Taxable	qime__Taxable__c
TaxExemptionReason	Tax Exemption Reason	qime__Tax_Exemption_Reason__c

* Value is hard-coded

Syncing Existing Accounts and Customers

Syncing existing customers within 2 data sets can be a challenging and laborious effort. While it would be nice to be able to link this data automatically, there are too many edge cases to make this possible. If you are looking to sync the two databases, the general workflow is as follows:

1. Export data from both systems.
2. Use VLOOKUP in an Excel sheet to match the databases on fields like name and email.
3. Update the qime__QB_Id__c field in Salesforce using the newly merged data.

If you are interested in a service like this, reach out to me here

Syncing Invoices

Next, we will cover how to sync invoices between QuickBooks and Salesforce. There are a few things that need to be configured before syncing with the two systems. These are:

• Linking products between QuickBooks and Salesforce
• Setting up the invoice terms

Syncing Products

Syncing products is essential to the QB linking if products in invoice line items are used in invoices. The products in QuickBooks can be linked to products in Salesforce, through the field qime__QB_Id__c. At a later release, this process of linking products will be simplified. At the time of writing, there is a good YouTube video on how to export products from QuickBooks to an excel sheet: 

Once products with Ids are exported, perform the following to link QB products with SF Products:

1. Link products from QB to Products in QB using Excel
2. Upload QB Ids to SF

Using only a 'Services' Line Item

Some companies do not want multiple line items on their invoices, and just use a simple Services product on the invoice. If you are looking to sync invoices with only a services line item, perform the following to have this configured:

Getting the Product ID From QuickBooks

To get the product ID from an individual product

1. Go to Settings -> Products and Services
2. Find the desired product.
3. Click on the down arrow, and select Run Report
4. Copy the URL into a text editor.
5. Find the item= URL parameter and copy down the id.

Configure in Salesforce

1. Go to Setup -> Custom Metadata Types
2. Go to QIME Config
3. Edit the Default record.
4. Use the following properties:
   1. Use Line Item - True
   2. QB Product Id - The product id from QB
5. Save the record.

Syncing Terms

Invoice terms are unique per instance of QuickBooks. Companies can also add additional custom invoice terms within QuickBooks. Thus, we need a way to sync the terms between environments. To do this, there are two places that the invoice terms are stored under:

• Terms custom field on the Invoice object.
• QB Terms custom setting to store the id mapping.

The Terms picklist on the Invoice object allows companies to show what terms are available to sync, while the QB Terms custom setting syncs all terms object stored within QuickBooks.

To add invoice terms:

1. Go to Setup -> Object Manager
2. Find the Invoice object
3. Find the Terms field under the Fields & Relationships section
4. Under the values section, add the terms that will be available to map to invoices.

To sync invoice term IDs:

1. Open the Developer Console
2. Run the following code snippet:

qime.QBTermBatch batch= new qime.QBTermBatch();
Database.executeBatch(batch, 50);

Syncing Invoices from QBO -> Salesforce

Syncing invoices from QuickBooks to Salesforce is essential for any QuickBooks integration. This allows data like payment date, balance due, and more to be synced with Salesforce, even if the invoice data is originating from Salesforce. First, let's take a look at how fields from QuickBooks are mapped to Salesforce.

QuickBooks Field	Salesforce Label	Salesforce API Name
AllowOnlineACHPayment	Allow Online ACH Payment	qime__Allow_Online_ACH_Payment__c
AllowOnlineCreditCardPayment	Allow Online CC Payment	qime__Allow_Online_CC_Payment__c
AutoDocNumber	True*	True
TotalTax	Tax	qime__tax__c
BillEmail	Emails	qime__emails__c
Customer Id	Customer Id	qime__Customer_Id__c
SyncToken	QB SyncToken	qime__QB_SyncToken__c
DocNumber	Document Number	qime__Document_Number__c
DocNumber	Name	'INV-' + qime__Document_Number__c
Txn Date	Transaction Date	qime__Transaction_Date__c
BCC Emails	BCC Emails	qime__bcc_emails__c
CC Emails	CC Emails	qime__cc_emails__c
Balance	Balance	qime__Balance__c
Terms	Terms	qime__Terms__c
Private Note	Message On Statement	Message_on_Statement__c
Delivery TIme	Delivery Time	qime__Delivery_Time__c
Due Date	Due Date	qime__Due_Date__c
Total	Total	qime__Total__c
Memo	Memo	qime__Memo__c

* Value is hard-coded

Schedule Invoice Sync From QuickBooks -> Salesforce

Invoices can be brought over hourly. To schedule Invoices syncing, perform the following:

1. Open the Developer Console
2. Run the following code snippet

   System.schedule('QB Invoice Sync XX:00', '0 0 * * * ?', new qime.QBInvoiceBatch());
   

This will sync invoices from QuickBooks to Salesforce at the top of every hour.

Sync All Invoices From QuickBooks -> Salesforce

During an initial setup, it is advised to sync all invoices from QuickBooks to Salesforce. To bring all invoices from QuickBooks to Salesforce, perform the following:

1. Open the Developer Console
2. Run the following code snippet

   System.enqueueJob(new qime.QBInvoiceQueueable(0, 0, 50, 0));
   

Schedule Payment Sync From QuickBooks to Salesforce

Payments need to be synced to Salesforce to not only get payment status and balance due, but also to see how much of a payment has been applied. The mapping document below describes how fields from QuickBooks map to the payment object in Salesforce.

QuickBooks Field	Salesforce Label	Salesforce API Name
Total Amt	Amount	qime__Amount__c
Transaction Date	Transaction Date	qime__Transaction_Date__c
Customer Id	Customer Id	qime__customer_id__c
Unapplied Amount	Unapplied Amount	qime__unapplied_amount__c
Id	QB ID	qime__qb_Id__c
Sync Token	QB SyncToken	qime__qb_SyncToken__c

To schedule payments syncing, perform the following:

1. Open the Developer Console
2. Run the following code snippet

System.schedule('QB Payment Sync XX:00', '0 0 * * * ?', new qime.QBPaymentBatch());

This will sync payments from QuickBooks to Salesforce at the top of every hour.

Sync All Payments From QuickBooks -> Salesforce

During an initial setup, it is advised to sync all payments from QuickBooks to Salesforce. To bring all payments from QuickBooks to Salesforce, perform the following:

1. Open the Developer Console
2. Run the following code snippet

   System.enqueueJob(new qime.QBPaymentQueueable(0, 0, 50, 0));
   

Conclusion

QIME is a great tool that connects Salesforce and QuickBooks. It is a flexible package that covers multiple use cases for companies. Additionally, it is free, open-source software (foss), so there is no need to pay high monthly fees to integrate your data. If you are interested in having QIME configured for you, reach out here to see how we can help out.

Github source code here

QIME is currently in the process of being approved on the AppExchange.