DIY Zoho QuickBooks Desktop Setup & Documentation

Thanks for using our DIY Zoho CRM & QuickBooks Desktop integration

This application is designed to sync information in Zoho CRM to QuickBooks Desktop, or the other way around. Some information can only be synced one way, and some of it can be synced both ways, depending on your need. The integration grabs the data you can sync from the available fields either in QuickBooks Desktop or Zoho CRM.

The integration is designed only to sync new and updated records across platforms, not all records, although if you use an annual payment plan (for premium versions of the integration), you’ll be able to sync any records across platforms based on dates as far back as you’d like. Please see section 4: Settings for more on data migration.

The first thing you’ll want to do is log into the application using the URL here. You may want to bookmark it for your convenience. The login page will require the credentials you created on the intake form. If you aren’t sure what the intake form is and you don’t have login credentials, you’ll want to read this page on completing the QBO integration intake form before continuing.

Please see the following table of contents for instructions on how to use each aspect of the integration dashboard and the integration itself.

QuickBooks Mapping
Logs
Filters
Settings
Upgrade Plan
Other Options
Using the Integration
A Few Provisos
FAQ

Before you start using the application, this is a tour of all the modules on the left-hand navigation bar.

1. QuickBooks Mapping

This is the default or home page you’ll see upon logging into the ZBrains dashboard. This screen allows for the mapping of different QuickBooks fields (on the left-hand side, marked by QB icons) with corresponding Zoho fields (on the right, marked with Zoho icons). Standard QuickBooks fields will be marked with green QB icons while custom QuickBook fields will be marked with similar red icons. Zoho fields will be marked with a regular Zoho icon regardless of whether the fields you choose are standard or custom.

The mapping works by selecting a Zoho field to map to each of the listed QuickBooks fields. By default, for all available modules, the integration will map some of the QuickBooks fields to Zoho fields. These mappings may not be to your liking, so please confirm they are correct before continuing.

To map a QuickBooks field to an unoccupied Zoho field: Click on the text field beside the field you’d like to map. A dropdown menu will appear, from which you can select any field you’d like. You can also type the name of the field you’d like if you already know its name, and the dashboard’s autocomplete feature will leave only field names that contain a match for the string you’ve typed. When you see the name of the Zoho field you’d like to map to the corresponding QuickBooks field, select that field by clicking it. Click “Submit” to save any changes.

If a field is occupied and you’d like to delete the mapping: Click the small X to the left of the field name or to the left of the field itself, then repeat the mapping process for an unoccupied field outlined above.

The following buttons are available in every module, regardless of the version you use:

Sync Mappable Fields button: This will grab all usable fields both from QuickBooks and from Zoho. This is useful when you’ve just added a custom field to either QuickBooks or Zoho and you’d like to map it. This also works if you simply don’t see a field in either QuickBooks or Zoho that you know already exists.
Reset Default Mapping button: If you don’t like how you’ve mapped the fields in your dashboard and you feel it would take too long to simply change them all back, you can use this button to return the mapped fields to how they looked when you first signed up for the integration. Some fields will already be mapped.
Reset button: This button is at the bottom of the screen. Use this to clear any changes you’ve made before hitting Submit. If you’ve already clicked Submit and changed your mapping details, you’ll have to manually make the changes you want and then click Submit again.
Submit button: This button, also at the bottom of the screen, saves any changes you’ve made on your mapping screen.

Also available is the Static Field checkbox beside every mappable field. Checking this box will delete the Zoho field mapping option from the associated QuickBooks field and allow for hard-coding a value into the QuickBooks field instead. Naturally, this means you can only assign a hard value to a QuickBooks field, not a Zoho field, so this feature is useful for Zoho-to-QuickBooks syncs. Possible use case: If every customer tracked in QuickBooks Online is on the same payment terms, you may choose to mark all payment terms a certain way for customers synced from Zoho to QuickBooks, e.g., “Net 30.”

2. Logs

You’ll be able to track which records the integration has interacted with by examining the Logs page. Different log screens are available for each available module, although the screen will default to Accounts if you don’t select an individual module page from the drop-down menu that appears after clicking.

When the integration interacts with a record, regardless of whether or not that record has been synced, the record will appear in the log. Newer synced records appear at the top of the log while older synced records are pushed to the bottom.

Following is an explanation of the items in the log table itself:

Module Key: The number that appears here corresponds to a record in Zoho CRM. You can view details for this record by clicking the blue Info button to the right of the record.
- To view the corresponding record directly in the CRM, highlight and copy (CTRL+C) the number displayed under the Module Key heading, navigate to Zoho CRM, find the appropriate module, and view any available record in the module. At the end of the URL for that record will be a long string of numbers, similar to the module key displayed in the sync log. Delete the number currently at the end of the URL and replace it by pasting (CTRL+V) the module key number you’ve just copied. Press enter and your browser will navigate to that record. This functionality serves to give the user a direct view of the record in case any changes to the record are necessary.

Status: This tells whether or not a record was synced by the system. Possible options here are Synced, Error, Not Synced, or Not Valid. Synced means the record was synced across platforms. Both Error and Not Synced mean the record was not synced because of an error. Not Valid means the record was not synced because of user-defined filters. Filters are further explained in section 3.

Error Message: This column displays the message associated with a sync error, if applicable. Errors are usually related to a problem with Zoho CRM accepting the info, not with QuickBooks. If you ever come across an error you do not understand, we offer support for any premium plan (that is, any plan that is not Freemium). Please contact us if you need help.

Last Sync Date: This shows the date and timestamp of each record in the sync log. You can use this to determine whether or not your integration is syncing by comparing the last sync date to the current date and time.

Details: This column shows a blue Info button for each record synced. Clicking this button will open a new screen within your browser window that shows all fields the integration has come in contact with. This is useful for giving an at-a-glance look at the record in question; alternatively, you can examine the record exactly as it appears in Zoho by using the record’s module key. (Please see the bulleted instruction with the Module Key item above.)

3. Filters

By default, the integration will sync any new or modified records across platforms depending on the sync direction you select. If you do not want all new or modified records to sync, you can choose to set criteria the integration will apply to all records it attempts to sync. Clicking the Filters module on the left-hand navigation bar will bring you to the Accounts filtering screen, but you can set filters for any available module.

The default filter screen will be for records synced from Zoho to QuickBooks, but you can set the same (or a different) filter for records synced from QuickBooks to Zoho if necessary. You can access the different sync directions with the drop-down menu in the upper right portion of the screen.

Here are the main options available to you in the Filter module:

Select Field: This drop-down menu displays a list of fields available inside the corresponding module in Zoho CRM or QuickBooks, depending on which module’s page you access. Selecting a field here tells the integration which field the filter will act upon.

Select Condition: This menu displays a list of basic conditions to apply to the field chosen in Select Field.

Value: This is a text field you can use to type any information you want the integration to act upon based on your selected field and condition. If your selected condition doesn’t require a value (e.g., “is not empty” or “is empty”), you should leave the Value field blank.

Use the blue plus symbol (+) to add another record filter in a given module and sync direction.

Use the green Submit button to save and apply any filter you have set. Click the red Reset button to clear any unsaved filter. And, use the dark blue Remove All Filters button to remove all filters you have set for the current module and sync direction.

4. Settings

The settings menu is comprised of a few tabs. Their uses and purposes are enumerated here:

Zoho Authtoken: This field contains the Zoho authentication token used when you filled out the integration intake form. The authentication token allows the integration to connect to your Zoho CRM instance, so if you remove it the integration will not work. If you need to switch authentication tokens for any reason, please replace a deleted token with a new one as quickly as possible to avoid any sync interruptions.

Sync Direction: This tab lists the available module pairs to sync, according to which version of the integration you’re using. You can use the drop-down menu to the right of each module pair to select whether you’d like to sync records in those modules from Zoho to QuickBooks, from QuickBooks to Zoho, both ways (Bi-Directional), or not at all (Disable).

Please note: Selecting “Disable” for any module pair will make the field mapping section for that module invisible, so you won’t be able to make any changes until the sync is re-enabled. As well, we do not advise disabling the sync for essential (Accounts/Customers or Products/Items) modules unless you are working with the Freemium version of the integration, as failure to sync those properly can potentially cause syncing of transactional records to fail.

Sync Historical Data [Annual customers only]: This tab lists the available modules from which to sync old records. In this case, an old record is anything created before the integration was implemented, as the integration is designed only to sync new or modified records; in cases where many records are present in one system and manually updating them all in order to trigger the integration’s sync would prove too time consuming, migrating historical data makes sense.

The Module Names heading lists the modules available to sync data from. Sync Date allows for choosing a historical date from which to sync data. The date can be modified across modules. Use the check boxes to the right of each module to confirm you wish to migrate data from that module across platforms, and click the Submit button to begin. The Reset button is not used.
- Please note: The sync directions for the Sync Historical Data tab are controlled by the sync directions set in the Sync Direction tab. If the proper module names do not appear on this screen (e.g., you see Customers, a QuickBooks module, instead of Accounts, a Zoho module), please change your preferred sync directions on the Sync Direction tab and the modules displayed will change accordingly on the Sync Historical Data tab.

Once your historical data migration tab is activated, you may use the function as often as you’d like.

5. Upgrade Plan

Clicking this module in the navigation bar will display your current integration plan juxtaposed with other available plans. You may upgrade or downgrade from one plan to another at any time without any lapse in functionality. When any plan is upgraded or downgraded, you will receive two emails: One confirming the cancellation of your current plan, and another confirming the beginning of a new service subscription. All upgraded or downgraded plans will come with new 15-day free trials, except for Freemium, which is always free to use. Please note: Your monthly service fee will not be prorated when your new subscription begins.

If you choose to upgrade to a paid plan from a Freemium plan, you will be prompted to enter your payment information. Once the system accepts this information, you will arrive back at the “Upgrade Plan” page and will have the option to map fields in new or different transactional modules by clicking the QuickBooks Mapping module in the navigation bar.
If you upgrade from one paid plan to another paid plan, or if you downgrade your plan, you will not be prompted to re-enter payment information.

6. Other Options

Clicking your username in the upper right corner of the screen reveals several other options:

QuickBooks Online: This is a general settings area for establishing the connection between the integration and your QuickBooks Online system. In most cases, you will not need to access the screen again after establishing the connection for the first time. The screen lists three steps to configuring the integration:

Authenticate: This step is completed in the initial intake form after you click the light blue Authenticate QBO button in Step 2 of the intake form. The background area of this step should be filled in with dark green, indicating the step has been completed. You do not need to do anything else with this step.
Verify: This is an extra step to ensure the connection between QuickBooks Online and our integration platform. If the background area of this step is not filled in with dark green as in the Authenticate step, please click Verify and follow the prompts you receive. Once this step is complete, the background area will turn green as it does with Authenticate.
Activate: After completing steps 1 and 2, the integration still will not function until you toggle the switch from “Inactive” to “Active.” The “Inactive” toggle will show a switch with a grey background, while the “Active” toggle will show a switch with a dark green background, similar to that used in steps 1 and 2. You can use this “Inactive” toggle to quickly turn the entire integration off, and the “Active” switch to turn it back on again.

Help: This link leads to the ZBrains help desk. Use this link to submit a ticket if you have a general question about setup, or you experience an error that is not covered in this document.

Logout: Clicking this link will log you out of the integration environment. The system will automatically log users out after 10 minutes of inactivity, so we advise you to either keep your password handy or have your browser save it for you.

7. Using the Integration

After familiarizing yourself with the various components of the integration dashboard, you should run a sync with some test records to confirm the functionality of the integration. To do this, please follow these steps:

Re-confirm your field mappings (see section 1) and your sync direction.
Open your platform of origin, either QuickBooks Online or Zoho CRM, and create a test Customer (in QuickBooks) or Account (in Zoho), making sure to include data in mapped fields. The sync will run automatically every 10-15 minutes, so please wait and confirm your test record has appeared in the destination platform after enough time has passed. Use the Logs module in your navigation bar to check on synced records.
- Please note: Users are unable to modify the sync interval currently, but this feature will probably be included in the next release.
Open your platform of origin again, and create a test Item (in QuickBooks Online) or Product (in Zoho CRM), making sure to include data in mapped fields. Again, wait until enough time has passed for the sync to occur. Use your Logs module to check on synced records.
- Please note: Once you have confirmed your Products or Items sync correctly, you may create a test transactional record as your service plan allows, but please ensure products or items used as transactional line items are synced to both systems before using them in transactional records. If these line items are not synced across platforms before creating a transactional record to sync, the transactional record you create will not sync.

Once you have confirmed the integration functions to your liking, there’s nothing else to do: the integration will continue to run at 10-15 minute intervals, syncing any records you input across platforms as you specify in your sync direction settings.

8. A Few Provisos

There are some things you should know about the integration that aren’t obvious from the onset:

The integration creates hidden custom fields in QuickBooks. When you implement this integration, all QuickBooks Customer and Item records will gain a new custom field called ZOHOMODULEIDCUSTOMER and ZOHOMODULEIDPRODUCT, respectively. These will be filled with values the integration uses to track sync states, and they are not mappable in the interface. For that reason, please do not modify the values in these custom fields, as doing so will cause certain records not to sync.
The integration only works with “Inventory” items in QuickBooks. Whenever you sync items from Zoho CRM to QuickBooks Online, they will arrive in your system as inventory items (as opposed to other types). Conversely, only inventory items (as opposed to other types) are allowed to sync from QuickBooks Online to Zoho CRM; other types of items will not sync. For this reason, we advise you not to change inventory item types manually after they sync to your QuickBooks Online, as they will not be updated back to Zoho CRM and, as a consequence, could cause certain other transactional records not to sync.
For bi-directional syncs, if a given record is modified in both Zoho CRM and QuickBooks Online between syncs, the record in QuickBooks Online will take precedence. In these cases, changes made to the records in Zoho CRM in this manner will be lost. We advise against modifying a given record in two different systems as a rule for this reason.
QuickBooks requires some Item fields; Zoho does not require the same information in Products. QuickBooks requires items to be mapped to expense accounts, income accounts, and asset accounts; Zoho CRM does not store this information, though. For this reason, you do not need to have these fields filled in Inventory Settings if you only plan to sync from QuickBooks to Zoho, but you will need to ensure they are correctly mapped if syncing from Zoho CRM to QuickBooks.
All Accounts/Customers and Products/Items should be synced across platforms before syncing non-test transactional records. This is because introducing a new Zoho account or QuickBooks customer – or Zoho product or QuickBooks item – at the same time as a new transactional record like an invoice, sales order, or quote/estimate, will cause the integration to fail. You may choose to keep accounts/customers and products/items inconsistent expressly to test the functionality of a transactional sync – for example, an invoice – by creating a test QuickBooks customer, test item, and then a test invoice containing that item and associated with that customer, but this practice is not advisable beyond testing. Please note: Data Migrations are required for all Integration projects and pricing varies on complexity of the integration itself. Typically, data migrations are priced based on the number of modules (ex. Sales Orders, Invoices, Customers are examples of modules) along with the number of records. Schedule an integration assessment today with a ZBrains consultant to get a project quote. Use the Connect with Us button at the end of the article.
Deleting a given record previously synced across platforms will cause the sync to fail if the non-deleted record is modified and needs to sync again. This is related to point 1, as the integration will search for a matching ID field that corresponds to a record already created, as the field does not exist for new records. When the integration does not find a matching ID field, the record will not sync. For this reason, we advise against deleting any records that have been touched by the integration unless you either plan to delete the corresponding record from the other platform or do not plan to modify the non-deleted record any further.

9. Frequently Asked Questions

Thankfully (or perhaps not), some issues with the integration are more common than others:

Why aren’t any of my fields appearing in the QuickBooks Mapping module when I log in for the first time?
- Sometimes, the integration needs a little positive reinforcement. If no mappable fields appear, first click “Reset Default Mapping.” If this does not cause your fields to appear, click “Sync All Mappable Fields.” If neither of these options work, please open a ticket with us here.
I just followed your instructions, but only some of my QuickBooks fields are appearing. What gives?
- The integration grabs fields from QuickBooks by looking at the fields that are being used by other records in your system. If you’re looking to map a field in QuickBooks that you’ve never used before, try creating a test record that utilizes those fields you don’t see yet, then click “Sync All Mappable Fields.” If this doesn’t solve the problem, please let us know about it.
I logged in for the first time and my Customers/Accounts fields appear, but none of my Products/Items are there. What happened?
- Are you on the free version of Zoho CRM? That one doesn’t have a Products module in it, so you won’t see any inventory fields that way. To solve that problem, please upgrade to a free trial of at least Professional edition and refresh your integration dashboard.
Upon setup, I got a red error flag saying “At least one inventory item must be present.” What do I do?
- This is somewhat related to question 2 above. To solve this problem, please create a test inventory item and return to your QuickBooks Mapping module, select Products, and click “Reset Default Mapping,” then “Sync All Mappable Fields” if no fields appear. If you still see the red error flag, open a ticket with us.
What does Static Field mean in my QuickBooks Mapping module? How do I use it?
- The Static Field option is used to assign a hard value to any QuickBooks field, but not to sync that value anywhere in Zoho. For more details on this feature, see the bottom of section 1: Mapping.
I got a big red error flag saying my QuickBooks Online credentials are no longer valid so the integration won’t work. How do I get it to work again?
- This means someone (maybe even you) must have changed your QuickBooks Online credentials without realizing that would affect the integration. Don’t worry; it happens to the best of us. To re-authenticate the integration, go through the QuickBooks Online steps in section 6: Other Options.
Some of my records are merged – or, they’ve been deleted! Did the integration do it?
- It wasn’t us! The QuickBooks Online API doesn’t allow for merging records or deleting them automatically, so we couldn’t have even done it if we tried. If you’re running plugins other than the Zoho CRM & QuickBooks Online integration, one of those may the culprit, as the issue may have to do with a program other than QuickBooks or Zoho.

Thank you again for using the QuickBooks Online integration with Zoho CRM. Please let us know if you have any questions or experience any issues this guide does not cover by calling (888) 207-4111 or using this link to our help center.

Connect with Us