QBO 2.0: Integrate with Quickbooks Online (QBO) via Integration hub

Before You Begin

You must have completed all steps in the Set Up QuickBooks Online (QBO) on the Developer Site article before you can complete setup in the Integration hub. 

Section Prerequisites

In the previous section, you received the Client ID and Client Secret from Quickbooks. 

  • If you do not have the credentials, review the section Obtain the Client ID and Client Secret. And, if you have requested but have not received the credentials yet from QuickBooks, here is how you follow-up with QuickBooks.

Account Connection

  1. Log in to Turvo and click your profile icon in the top right corner of the page. Then, select Admin console.
    2024-02-13_11-49-06.png

  2. Select the Integration Hub tile.


  3. Select the Quickbooks tile.
    2024-02-13_11-49-51.png

  4. Enter the Client ID and Client Secret obtained from QBO into the appropriate fields in the Connect block. Then, click CONNECT TO QUICKBOOKS to establish your connection.


  5. Once a successful connection is established, you’ll be redirected to Turvo’s Integration hub to proceed with mapping Turvo to your Quickbooks chart of accounts.

Important Connection Considerations:

  • It may take a few minutes for the connection to complete. If it takes longer than 5 minutes and the CONNECT TO QUICKBOOKS button is still greyed out after refreshing the page, contact Turvo Support or your Turvo representative for further assistance.
  • If you are already logged in to your Intuit/QuickBooks account, you’ll automatically be redirected to QuickBooks for validation of the Client ID and Client Secret. 
  • If you are not logged in to your Intuit/QuickBooks account, you’ll be redirected to a QuickBooks screen, where you’ll be required to log in to your QuickBooks account for validation of the Client ID and Client Secret.
  • If the connection is unsuccessful, you’ll see a QuickBooks failure notification. 
    • Close the Intuit/QuickBooks failure notification window. Refresh Turvo’s Integration hub screen. Enter the correct Client ID and Client Secret and click CONNECT TO QUICKBOOKS.

Resetting Your QBO Connection

At some point, you may need to reset your QBO connection. You may have integrated Turvo with an incorrect company in QBO or you need to update your mappings.

CAUTION: Resetting an existing connection could lead to deletion of all existing chart of accounts mappings in Turvo. In such an event, you will be required to map your chart of accounts in Turvo to the corresponding chart of accounts in QuickBooks again. Exercise utmost caution when deciding to reset your existing connection. 

CAUTION: Resetting your existing connection - along with your existing chart of accounts in Turvo that are mapped to corresponding accounts in QuickBooks, will create sync issues for invoices and payments that are partially done in Turvo. 

For example:

  1. Your Turvo tenant ‘A’ has an existing connection (and chart of accounts mappings) with your account ‘X’ (QBO ID: 123X) in QuickBooks.
  2. You create a carrier invoice ‘1’ for an amount of $100 in Turvo and on approval, this invoice syncs with your account ‘X’ in QuickBooks. 
  3. Then, you choose to reset your existing connection (along with your existing chart of accounts mappings) with your existing account ‘X’ to your account ‘Y’ (QBO ID: 456Y) in QuickBooks.  
  4. After that, you create a payment for $100 (from carrier invoice ‘1’) in Turvo. This payment tries to sync with your account ‘X’ (QBO ID: 123X) in QuickBooks and fails - because the connection with your account ‘X’ in QuickBooks (along with the chart of accounts mappings) is lost.

The solution: You’ll be required to perform the following steps in Turvo:

Step 1: Delete your payment for $100.

Step 2: Delete (archive) the carrier invoice ‘1’.

Step 3: Create a new carrier invoice ‘2’ for the amount of $100 and on approval, this new invoice syncs with your account ‘Y’ (QBO ID: 456Y) in QuickBooks. 

Step 4: Create payment for the $100 (from carrier invoice ‘2’). Now this new payment syncs successfully with your account ‘Y’ (QBO ID: 456Y) in QuickBooks.

Follow the steps below to reset your QBO Connection:

  1. Admin and Super Admin roles have the ability to reset the QBO connection by navigating to Admin console > Integration hub > My integrations and clicking the Quickbooks tile.


  2. Click RESET CONNECTION.


  3. Once you click Reset Connection, a caution message Resetting the connection may also reset existing custom mapping with QuickBooks. Do you want to proceed? is displayed with Cancel and Reset Connection options. While the Cancel option nullifies your reset connection action, the Reset Connection option resets the Client ID and Client Secret to blank.


    Note: At this stage the existing chart of accounts mappings are still intact.

Entering an existing Client ID and Client Secret 

Turvo detects and ensures that the entered Client ID and Client Secret are existing credentials and presents a pop up notification box with two options regarding the existing chart of accounts that are either partially or completely mapped in Turvo:

  • Keep the current mapping: Click this option to retain the existing chart of accounts mappings.
  • Delete the current mapping: Click this option to delete  existing chart of accounts mappings and set up new mappings.

2024-02-13_11-53-24.png

CAUTION: The Delete the Current Mapping option deletes all existing chart of accounts mappings in Turvo. In such an event you’ll be required to map your chart of accounts in Turvo to the corresponding accounts in QuickBooks again. Exercise utmost caution while resetting your existing connection. 

Entering a new Client ID and Client Secret 

Turvo detects and ensures that the entered Client ID and Client Secret are new and presents you with a caution message, The existing mapping will be deleted. You have entered a new Client ID and Client Secret. All existing mappings across sections will be deleted is displayed with Cancel and Delete the Current Mapping options. 

While the Cancel option nullifies your reset connection action, Delete the Current Mapping option will:

  • Delete your existing chart of accounts that are either partially or completely mapped in Turvo.
  • If you’re already logged in to your Intuit/QuickBooks account, you’ll automatically be redirected to Intuit/QuickBooks for validation of the entered Client ID and Client Secret. 
  • If you’re already not logged in to your Intuit/QuickBooks account, you’ll be redirected to a Intuit/QuickBooks screen, where you’ll be required to log in to Intuit/QuickBooks account for validation of the entered Client ID and Client Secret.
  • Once successful, you’ll be redirected to Turvo’s Integration hub to proceed with mapping the chart of accounts in Turvo to the corresponding accounts in QuickBooks
  • If unsuccessful, you’ll see a Intuit/QuickBooks failure notification
    • You’ll be required to close the Intuit/QuickBooks failure notification window, refresh Turvo’s Integration hub screen, and enter the correct Client ID and Client Secret.

Map Turvo to your QBO Chart of Accounts

Important Mapping Considerations

  • We recommend that, regardless if you use a specific carrier/customer cost today, you should still map all items to the desired chart of accounts. That way, if you use a “new” cost in the future, it will map appropriately and minimize any syncing issues.
  • You must complete the mapping process and click COMPLETE SETUP before changes can be made to your selections. 

Carrier and Customer Costs



These sections allow you to decide how to map your Turvo carrier and customer costs to your QBO general ledger account(s). Both carrier and customer costs have seven sections to map.

For each section, it is recommended best practice to select the default QBO account type and account. This is the default account type and account for all cost items within each section, unless otherwise specified in the individual mapping. You don’t need a 1:1 relationship with each cost item. For example, all carrier cost items, regardless of their grouping (accessorial, freight, fuel, etc), can map to all cost of goods sold (COGS).

The account options available in the drop-down menus are automatically pulled from your QBO chart of accounts. If you don’t see a specific general ledger account in the drop-down, you need to create it within your chart of accounts in QBO first and then return to Turvo.

In the image below, the Carrier freight account mapping is shown. The default account is indicated by the red box. When the default account type and account is selected, all individual options populate with the default. You can map individual options with another account type and account, as indicated by the arrow.



Note: Each section is scrollable to see the various options. 

It is very important to properly map each item to the correct account because incorrect mapping can result in failed invoices, invoices with incorrect financial information, and information synced from Turvo to QBO could be inaccurate.

Turvo recommends that you have an accountant or accounting specific person map as Turvo is unable to advise you on how you should map Turvo to your Chart of Accounts. 

Important Note: It is very important that you do not map carrier information to an accounts receivable (AR) account, as this generates an error code. 

Payment Types

In this section, you map Turvo’s payment types to your QuickBooks chart of accounts and determine where you would like to record payments. The Payments section is split into the following sections:

  • Payment preferences
  • Carrier payment mapping
  • Customer payment mapping
    • Note: Customer payment mapping is only available when Quickbooks is selected in the Payment preferences section.

Payment preferences

In Payment preferences, you determine if you want to record payments in Turvo or QBO. 

Important Note: Payments recorded in the system of record will sync to the other platform, but not the other way around; only one platform can be the system of record.
2024-02-13_11-56-27.png

When Turvo is selected as the system of recorded payments, data flows from Turvo to QBO.
 

When Quickbooks is selected as the system of recorded payments, data flows from QBO to Turvo. 

Important Note: If you selected Quickbooks as your system of recorded payments, you must enter Endpoint URLs.

Carrier Payment Mapping

In this section, you will map Turvo’s carrier payment types to your QuickBooks chart of accounts. 

Important Note: If you haven’t already, you must configure the payment terms, methods, and advances settings for your tenant through the Admin console. See our How to adjust payment terms, methods, and advances in Admin Console for more information.

The account options available in the QuickBooks account drop-downs for Payments, Deductions, and Holding account are automatically pulled from your QBO chart of accounts. For each section, select the appropriate option from the drop-down menu. 

Once you’ve entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move onto the next section.

Customer Payment Mapping

Important Note: This section is only available when Quickbooks is selected in the Payment preferences section.

In this section, you will map Turvo’s customer payment types to your QuickBooks chart of accounts. 

The account options available in the QuickBooks account drop-downs for Payments are automatically pulled from your QBO chart of accounts and Payment methods options are pulled from the payment methods in QBO. For each section, select the appropriate option from the drop-down menu. 

Once you’ve entered all of the appropriate mapping, click SAVE PROGRESS in the bottom right corner to move onto the next section.

Shipper and Carrier ID

The Shipper ID and Carrier ID sections allow you to map historic shipper and carrier IDs from any existing QBO data with your Turvo shipper and carrier IDs.

Important Note: If you have existing carriers and customers in Turvo that you created before enabling QBO, you must manually add the Quickbooks Online ID in those carriers and customers profile in Turvo. From the Main Navigation bar, go to Accounts > Carriers > select the Carrier > Details > Accounting:

Mapping Shipper IDs and Carrier IDs for the First Time 

If you are new to QBO and are mapping Shipper and Carrier IDs for the first time, click the Shipper ID or Carrier ID section of the self-serve screen to view the options:

  • through the TDI process and 
  • manually via a Turvo file.

Note: In addition to the two options, you’ll see a third option (in disabled mode) that provides you the ability to edit the previously uploaded Turvo mapping file. This additional option will be enabled only when you’ve done the mapping manually using option 2.

Select the TDI option only if you’ve done the Shipper ID and Carrier ID mapping through the TDI process. 

Select the manual option, if you would like to do the mapping manually using a Turvo file. 

When you select the manual option, the Download link becomes available. Click the download link to download two files, a Turvo file with Shipper Names and their IDs, and a QBO file with Shipper/Carrier IDs

Combine the two documents by entering the correct QuickBooks ID into the QuickBooks ID column of the document that contains the Turvo ID and name, then save it as a .csv before uploading.

Then upload the Turvo file to the upload box provided and click Process.

Important Note: Turvo recommends using an application like Numbers or Excel to edit the downloaded files. Before uploading file, make sure that is it saved as a .csv before you click Process.

Important Note: For both files to download properly, you must have the Chrome setting Ask where to save each file before downloading set to OFF . In your Chrome browser, navigate to the three dot menu > Settings > Downloads and toggle OFF Ask where to save each file before downloading. The download save location will vary based on your browser type and version. 

Important Note: If you do not map your carriers and shippers at this time and operate out of your existing QBO, Turvo will create a duplicate in QBO. Mapping the ID’s is required for existing accounts.

Editing Mapped Shipper IDs and Carrier IDs

In the case you have incorrectly mapped the QBO IDs to the Turvo IDs, sync issues happen. You can edit the previously uploaded Turvo mapping file by selecting the edit option.

When you select the third option to download the previously uploaded Turvo mapping file that you previously uploaded. Edit the QBO IDs as needed in the Turvo file, upload it in the upload box provided and click Process

Note: The edit option is not for mapping done via the TDI process. You’ll be able to use this option only if you have uploaded the Turvo file with mappings previously using the manual option.

Custom Fields

You can map up to three Secondary ID types to custom fields on your QBO customer invoice. 

Note: If you are enabling custom fields for the first time, only future invoices will show custom fields; previously created invoices are not affected. 

This section is optional; Turvo will continue to send the Invoice number and the Primary shipment ID to QBO if you choose not to map this section.

Note: Due to QBO limitations, mapping secondary IDs to the carrier invoice is not available.

Before you can map in Turvo, you must have Custom Fields set up in QBO in Settings > Custom fields.

In QBO, for each custom field, you must click the checkbox for each option below in order for custom fields to populate in Turvo:

  • Sales Receipt 
  • Invoice
  • Estimate
  • Credit Memo
  • Refund Receipt

2024-02-13_12-00-23.png

2024-02-13_12-01-16.png

To map in Turvo, select the Turvo Secondary ID from the drop-down and then select the Quickbook Custom Field from the drop-down. 

Note: The API only returns the three oldest custom fields from QBO, including disabled custom fields. If needed, you can rename the three oldest custom fields in QBO. You must create custom fields in QBO before those fields will be available to select from Turvo Integration hub.

After Mapping: Finish Setup

Once all of the above mapping is complete, click COMPLETE SETUP at the bottom right corner of the page to finish the connection. If mapping is not complete, the COMPLETE SETUP button will remain grey.

2024-02-13_12-02-22.png

Important Note: The connection will not be successful without clicking this button.

Test Shipper and Carrier ID Mapping

Follow the instructions below to test that your Shipper and Carrier IDs were mapped correctly:

  1. Select 10-15 customers and carriers and for each, navigate to the customer or carrier account by via Accounts > Customer or Accounts > Carrier in the left navigation bar.
    image12.png

  2. Then, click the Details tab and scroll down to the Accounting section. Expanding this section will show any imported QBO IDs, and you can edit them in this section as well.
    2024-02-13_12-03-56.png

Protip: You can find customer and vendor (carrier) QBO IDs by logging into QuickBooks and navigating to the customer or vendor entity. The QBO ID is the number located at the end of the URL (as shown below).

2024-02-13_12-04-46.png

Next Up

Now that you have completed all of the steps in the Integration hub, head over to our Post Setup Testing, FAQs, and Troubleshooting article to test your QBO connection.

Was this article helpful?

0 out of 0 found this helpful