Halo Service Desk Guides
Documentation to assist with the setup and configuration of the Halo Service Desk platform
QuickBooks Online Integration
Enabling the Module
To enable the QuickBooks Online integration, go to Configuration > Integrations > Billing, and enable the module using the plus icon in the top right hand corner of the menu icon. Once the module has been enabled, click the menu icon to begin configuring it.
Connecting to QuickBooks Online
You are required to connect to your QuickBooks Online account before you can proceed with any further configuration. Start the authorisation process by clicking the Connect to QuickBooks Online button.
You will be redirected to the QuickBooks Online login screen. Once logged in, you will be asked to choose which company you would like to connect to. Confirming this choice will redirect you back to the QuickBooks Online module in Halo, where you will now see the rest of the configuration options available.
The top section of the module now displays the company which you are connected to. Should you wish to change this, or remove Halo's access, use the disconnect button.
You can also see from this screen whether or not automatic sales tax has been activated for your QuickBooks account. This feature is currently only available to US QuickBooks Online users. When activated, all lines on an invoice in Halo will display zero tax until the invoice is synced to QuickBooks. At this point, QuickBooks calculates the tax for you and the total tax for the invoice will be written back to the invoice in Halo. The lines on the invoice will remain as zero tax in Halo.
In some circumstances, QuickBooks' preferences will not show automatic sales tax as being enabled, even though it has been enabled for your QuickBooks account. This means that automatic sales tax won't be enabled in Halo, which will then cause issues when syncing invoices. If you believe that your company uses automatic sales tax but it has not been automatically enabled for you in Halo, speak to a member of the Halo support team who will be able to activate it for you.
Before proceeding with any further configuration, you must make sure that every tax rate in Halo is linked to a QuickBooks Online tax rate. This can achieved by either importing all of your tax rates from QuickBooks, or opening each Halo tax rate manually and choosing a QuickBooks tax rate from the drop down available.
IMPORTANT: This step of the configuration is compulsory. Skipping this step will result in errors when syncing invoices later.
To manually assign the tax rates, click the Edit Tax Rates button and open any tax rate in the list. The final field on the tax rate will list all of your currently available tax rates in QuickBooks. Select the corresponding tax rate and save this to assign the QuickBooks rate to the Halo tax rate.
To import all tax rates automatically, you must first specify which tax rate should be assigned to the zero tax rate in Halo. In this example, NOTAXS is the QuickBooks tax rate for sales which is 0% tax. Simply type the name of this rate into the field before importing and this will ensure that the tax rate is correctly assigned to the zero tax rate in Halo.
When ready, click the Import Tax Rates button to begin importing your tax rates. If successful, a popup will display showing how many rates have been imported.
It is recommended that you go back through your tax rate list in Halo once complete to ensure that you do not have any tax rates in Halo that are not assigned to a QuickBooks tax rate. This may be the case if you already have tax rates in your database.
Now that tax rates have been configured, you can move onto importing customers. In order for invoices to sync, each customer in Halo must be assigned a QuickBooks Online ID, so you should ensure that all of your customers are imported from QuickBooks if you want to be able to sync their invoices across.
IMPORTANT: This step of the integration is compulsory if you want invoices for a customer to be synced. If the customer already exists in your system, but is not assigned a QuickBooks Online ID via this import, their invoices will not sync.
Due to the requirement that a customer must have a name in Halo, only customers with a company name in QuickBooks can be imported.
IMPORTANT: It is not enough for a customer to have a first and last name in QuickBooks, as this is not the company name. The "Company" field must be populated (Bosch in the below example).
When importing, existing customer records in Halo will be updated if they have the same name in Halo as they do in QuickBooks. If they are being imported for a second time, then the record will be updated based on the QuickBooks ID that has been previously assigned to the record.
When you are happy, click the Import Customers button to open the importer screen, where your customers from QuickBooks will be listed for you to import.
Once you have imported at least one record, navigate to the customers view and open a customer that has been imported. On the settings tab of this customer, you will find under billing settings that the customer has now been linked with a QuickBooks customer.
You will also notice that the tax rates for this customer have been set to Use Item Tax for all tax options. This is due to the way QuickBooks handles tax. These values can be modified if you wish, but you must ensure that any tax rate you choose has been linked to a QuickBooks tax rate.
Now that your customer list has been imported, you now need to import your products and services from QuickBooks. When syncing invoices to QuickBooks, every line on the invoice must be linked to an item that exists in QuickBooks. Therefore, you must ensure that all products and services that you want to sync to QuickBooks have been imported.
IMPORTANT: This step of the integration is compulsory if you want to use the item on an invoice. If the item already exists in your system, but is not assigned a QuickBooks Online ID via this import, the invoices sync will fail.
When importing, existing item records in Halo will be updated if they have the same name in Halo as they do in QuickBooks. If they are being imported for a second time, then the record will be updated based on the QuickBooks ID that has been previously assigned to the record.
If an item is inclusive of tax in QuickBooks, then they will have their tax rates set to 0%. The tax rate fields against an item will remain adjustable, but changes to these fields will not be reflected in QuickBooks when syncing back.
Before importing, you must choose an item group that will be used for services and inventory items. This will allow Halo to differentiate between what is a service and what is an inventory item. This is particularly important when it comes to syncing items back to QuickBooks later, as an inventory item will display different fields to allow the sync to QuickBooks to be successful.
IMPORTANT: You must not select the same group for both types of item.
When you are happy, click the Import Items button to open the importer screen, where your products and services from QuickBooks will be listed for you to import.
Once you have imported at least one product or service, navigate to the items view and open one of the items you have imported. Under billing settings, you will see that the item has now been linked to a QuickBooks item. Providing you have correctly setup your tax rates, you will see that the tax rates have also been set on the item.
For any service item which has been created, a charge rate will be created for you. Charge rates are configured in Configuration > Billing > Charge Rates. In the above example, the service item "Hours" has been created and linked to item code 2:
IMPORTANT: Any charge rate that you would like to use on actions that will eventually be synced on invoices to QuickBooks must be assigned to a QuickBooks item. If you have additional charge rates that are not linked to items, you can manually link these by populating the Accounts Item Code field with the QuickBooks item ID you want to link it to.
If there are any charge rates that have been created for service items that you don't want to use, then these can be safely deleted.
Syncing to QuickBooks
Now that you have imported tax rates, customers and items, you are ready to enable syncing to QuickBooks. By enabling this feature, whenever you create or update a customer or item in Halo, the changes will be synced to QuickBooks. If the customer or item in Halo is correctly linked to a QuickBooks record, then the record will be updated in QuickBooks, otherwise a new record will be created.
Once you have checked the option to enable syncing, some additional options will be displayed.
As mentioned earlier in this guide, every item on an invoice must be linked to an item, otherwise the invoice will fail to sync correctly to QuickBooks. It can be difficult maintaining a fully synced item list, so to help with this, we have added an option to choose a default item for invoices. This means that if you do accidentally add an item to an invoice which is not linked to a QuickBooks item, then the default item will be assigned to the line so that the invoice won't fail to sync. We recommend using a miscellaneous item for this field, which is a common piece of configuration in all accounts systems.
The email status for new invoices field is simply a default that will be set for all invoices, so this can be set to any of the available values.
Finally, there is an option to show a message whenever a sync is successful. It is highly recommended that you enable this feature, particularly when first using the integration, as it gives a good indication that the actions you are taking are working.
Example: with this feature enabled, if you try to sync an invoice for a customer who has not been correctly linked to a QuickBooks customer, then no popup will display, which will indicate to you that Halo has not tried to sync the invoice to QuickBooks.
When you are creating a new customer, there are some compulsory fields that must be completed for the sync to be successful. The two required fields are the first and last name of the main contact for the customer, which are denoted as mandatory by the red star against the field. These fields can be found under the Billing Settings heading on the settings tab:
For US customers using this integration, you are also required to specify a default tax code. This field will also have a red star to indicate that it is mandatory.
WARNING: Failure to choose these fields will result in error messages from QuickBooks being given. The most common of these is a 6000 Business Validation error message. If you see this error, ensure that you have correctly populated all mandatory fields against the customer record.
Like customers, items have compulsory fields that must be completed when you create them in order for the sync to be successful. Earlier in the configuration, you should have chosen an item group that will store QuickBooks inventory items. When creating a new item, if you assign it to this group, then the field will be created as an inventory item in QuickBooks. Items created in any other groups will be created as service items.
All mandatory fields for the QuickBooks sync can be found under Billing Settings. If you are creating a new service item, the following fields are mandatory and will have a red star next to them:
- Income Account
- Tax Code (Sales)
- Tax Code (Purchases)
When selecting tax codes, picking a tax code that isn't linked to a QuickBooks tax code will result in an error when saving the record.
In addition to the fields listed above, inventory items also require you to specify the following fields:
- Inventory asset account
- Quantity on hand
- Inventory start date
Some of your technicians will not know what income/expense/asset inventory accounts should be set when creating an item, which is why we have implemented a default option for these fields. These defaults can be configured in Configuration > Items and Stock Control > General Settings, so whenever your technicians create a new item, these fields are automatically populated for you:
Providing all steps of this guide have been followed, and every entity in Halo is correctly linked to an entity in QuickBooks, syncing invoices will be straightforward. All types of invoices can be synced to QuickBooks, whether it be for labour on tickets or an invoice created from a recurring invoice. We will only look at raising a basic manual invoice in this guide for simplicity.
When first adding an item to an invoice, the item code will be displayed on the invoice line:
This is the first basic indication that the item you've added to the invoice has been successfully linked to a QuickBooks item. If no item code is shown, you can either edit the line and manually adjust the item code, or when the invoice is saved, if you have chosen a default item for invoice lines then the line will automatically be assigned the default item's code.
When saving the invoice, there are some common errors that can occur due to misconfiguration. If the error mentions tax rates not being specified or being invalid, then the item that is assigned to your invoice line is likely not assigned to a tax rate which has been linked to a QuickBooks tax rate. Likewise, if the error contains information about an invalid item on the invoice, then one of your items/charge rates has not been correctly linked to a QuickBooks item.
In these circumstances, you should revisit your configuration and check that these entities have been linked together correctly. Once you've made changes to your configuration, you should re-add the line to the invoice so that the changes take effect on the invoice. As long as one field/line is modified, then the changes will be synced across to QuickBooks.
Updates to invoices that have already successfully synced to QuickBooks will also be synced to QuickBooks, for example, if you wanted to increase the quantity of an existing invoice line.
Should you wish to remove an invoice, deleting it from Halo will remove the invoice from QuickBooks. The deletion from Halo will also roll back any billing calculations, so tickets that were billed on the invoice will now re-appear in the ready for invoicing section.
If invoices are created in QBO but do not have an invoice number then please use the below to resolve.
- Asset Import - CSV/XLS/Spreadsheet Method
- Call Management in Halo
- Creating Agents and Editing Agent Details
- Departments, Teams and Roles
- Importing Data
- Multiple New Portals with different branding for one customer [Hosted]
- Organisation Basics
- Organising Teams of Agents
- Step-by-Step Configuration Walk Through
- Syncing Exchange Calendars