HaloPSA Guides

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 "QuickBooks Online Companies" button.

You can then add in Quickbooks tenants to begin configuring the integration. As QuickBooks is a multi-tenanted integration, you can configure multiple QBO companies in Halo in order to split up the QBO companies for different customers. To begin configuring a tenant click new in the top right corner of the screen and then click "connect". 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. 

When in the editor view within the details tab, the top section of the module now displays the company which you are connected to and a disconnect button. 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.

Tax Rates

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 be 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, No Tax 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.

Customer Imports

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.

As of v2.161 there is the ability to map sub customers in Quickbooks to the Sites in Halo, this is acheived via the mappings table found in the Customers tab of the integration.

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 name" 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 Billing 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 (The tax code options shown in the below screenshot will only be visible if the "Is Taxable" checkbox is checked on within the Billing Tab of the customer) have been set to Use Item/ Product Tax for all tax options (The use of Products/ Items in this guide are interchangable). 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. Additionally you can set tax rates at the site level witihn the sites billing tab, if you wish to tax each site of that customer differently

Product/ Item Imports

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 product 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 service products, inventory products and non-inventory products. 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 Service Products and Inventory Products. It is best practice to have this configuration to be unique product groups for each product type in QBO, it is possible to have Service Products and Inventory Products using the same Product Group in Halo, although you must have asset inventory accounts for the Service Products in QBO. Another important thing to consider is that Products exported to Quickbooks Online from an unmapped Product Group will be created in Quickbooks Online as Service Products.

The various types of accounts can also have defaults set for new Products. 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 product. If you have additional charge rates that are not linked to products, you can manually link these by populating the Accounts Product 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 products that you don't want to use, then these can be safely deleted.

Suppliers

Suppliers can be imported from QuickBooks Online into HaloPSA. When importing a Supplier for the first time, HaloPSA will check to see if a Supplier already exists with the same name or accounts code. If found, the existing Supplier record will be updated. The name changes made in Halo will be synced to QBO if Supplier is within the entities to sync.

Syncing to QuickBooks

Now that you have imported tax rates, customers and products, 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 QBO. 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.

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.

Sync Classes to invoice lines - When enabled this will allow class information to be synced to QuickBooks when the invoice is created in Halo. Class information can be set against each product using the 'Class for Invoice reporting/tracking' against the product.

Don't include lines that are used to track costs only - Lines that have 'track cost only' enabled will not be synced to QBO

QuickBooks Custom Field to use for Halo Invoice PO Number - Here you can select the field that the Halo purchase order number is saved to when syncing to QBO. This only applies to invoices that are linked to a purchase order. 

Void Invoices in Quickbooks Online when they are marked as void in HaloPSA - When an invoice is marked as 'void' in Halo this will be marked as 'void' in QBO too. 

Don't sync quantity on hand to Quickbooks - When enabled the number of items you currently have in stock will not be synced to QBO

Purchase Orders

Purchase orders can be synced from Halo to Quickbooks. To enable this, add purchase ordered to the 'entities to sync' field. 

You must set a default item for purchase orders. If an item on the purchase order does not have a QBO item linked to it this will be the item that it is linked to. It is best to set a generic item here. 

Account for Purchase Orders- Choose which account will be linked to the purchase order once it is synced over.

Email Status for New Purchase Orders - This is the email status the purchase order will have once created in QBO. 

Webhooks

Under the 'webhooks' tab you can enable various webhooks for the integration.

Enabling webhooks allows changes to be synced as soon as a client or payment is created or updated. 

There are some additional settings here too. When 'Unapplied payments will be removed from Halo' is enabled any payments against an invoice that are removed in QuickBooks will set the payment to 0 in Halo and remove the QuickBooks reference from the payment. 

Syncing Customers

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.

Syncing Items

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. 

NB: When creating quotes/ invoices in Halo, only items synced to the same QBO instance as the customer will show when adding 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:

Syncing Invoices

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.

Common issues

If invoices are created in QBO but do not have an invoice number then please use the below to resolve.

1. Go to the Gear icon, then choose Account and Settings.
2. Select the Sales tab.
3. Click anywhere within the Sales form content section.
4. Uncheck the box next to Custom transaction numbers.
5. Click Save and then Done.

Sync the Halo Invoice ID to QuickBooks

This feature should only be enabled if there is no possibility of a Halo Service Desk invoice ID clashing with an existing QuickBooks Online invoice ID. Custom transaction numbers must be enabled in QuickBooks Online to use this feature. A guide explaining how to enable these can be found here.

When enabled the "ID" field on the Invoices in Halo, will sync over to QuickBooks:

The third party invoice number represents the invoice number that would be pulled from QuickBooks.

If products are being synced, there is also the checkbox option (On version 2.150.1 or higher) 'Don't sync quantity on hand to Quickbooks' when this is enabled, it will stop the syncing of item quantities to QBO for inventory types.

Symbols for Customers Not Synced to QuickBooks

When customers are not currently synced to QBO, they will be marked with a cross symbol, this allows distinguishment between the customers that are synced and those who aren't. The customer list will display the following for those customers: