QuickBooks Desktop

Overview

This article explains how to connect your Kompass account to QuickBooks Desktop for automatic syncing of clients, projects, and invoices. Only admin users can set up and manage the QuickBooks Desktop connection.

QuickBooks Desktop has no cloud API, so the connection works differently from QuickBooks Online or Xero: a small Intuit utility called the QuickBooks Web Connector runs on the Windows machine that hosts QuickBooks and securely polls for changes on a schedule you choose. Kompass sends changes through our integration partner Conductor, and the Web Connector applies them to your company file the next time it checks in. This means the sync is near real-time: changes typically appear in QuickBooks within a few minutes, depending on the polling schedule.

The integration supports QuickBooks Desktop Pro, Premier, and Enterprise on Windows. QuickBooks Online is covered by a separate article. If your QuickBooks Desktop is hosted in the cloud (for example with Rightworks), contact Kompass support before starting.

Prerequisites

• QuickBooks Desktop installed on a Windows machine, with admin access to the company file you wish to connect
• Access to that machine during setup (the Web Connector handshake happens there)
• Admin access to your Kompass account
• The QuickBooks Desktop permission group on your user. If you do not see a QuickBooks Desktop group in the Admin site, contact Kompass support to have the permissions added to your account.

Step 1: Create a QuickBooks Desktop Configuration

1. Navigate to the Admin site by adding /admin after your Kompass URL (e.g. your-server.kompassbms.com/admin).
2. Under the QuickBooks Desktop group, select Configurations.
3. Click Add in the top right to create a new configuration.
4. Select the Kompass organisation to link to this QuickBooks company file.
5. Add at least one email address under Notification recipients. This is required before connecting, and sync error notifications will be sent there.
6. Click Save. Leave the Enable checkbox unticked for now; you will enable the sync in Step 5 once existing customers have been reconciled.

Step 2: Connect via the QuickBooks Web Connector

1. On the Configurations list page, select the configuration you just created using the tick-box.
2. From the Action drop-down menu, select Connect to QuickBooks Desktop via Conductor and click Go.
3. You will be redirected to a guided setup page. Complete this page on the Windows machine that runs QuickBooks; if you are not at that machine, copy the link and open it there.
4. Follow the on-screen steps: install the QuickBooks Web Connector if it is not already present, download the connection file (a small .qwc file), open it in the Web Connector, and enter the password shown on the setup page.
5. QuickBooks will ask you to authorise the connection. Have the company file open and be signed in as the QuickBooks admin user, and allow access even when QuickBooks is not running when prompted.
6. In the Web Connector, tick Auto-Run for the new entry and set the polling interval (every 5 to 15 minutes works well for most companies).

Step 3: Confirm the Connection

1. Back in the Kompass Admin, select the configuration again.
2. From the Action drop-down, select Refresh QBD connection ID from Conductor and click Go. This picks up the connection created by the Web Connector handshake and stores it on the configuration. If it reports that no connection exists yet, the handshake has not completed; finish Step 2 first.
3. Run the Check QBD connection health action to confirm QuickBooks is reachable. The Last seen at field on the configuration shows when the Web Connector last checked in.

Step 4: Reconcile Existing QuickBooks Customers

To reconcile existing QuickBooks customers and jobs with Kompass clients and projects before enabling the sync:

1. On the Configurations list page, select your configuration using the tick-box.
2. From the Action drop-down, select Compare QBD customers with Kompass (email CSV) and click Go. Kompass fetches every customer and job from the company file (including inactive ones, since QuickBooks does not allow a new customer to reuse an inactive customer's name), matches them against your Kompass clients and projects by name, and emails a download link for a CSV report to the address on your user account. This typically takes a few minutes.
3. Open the CSV. Each row shows a QuickBooks customer or job, a candidate Kompass match, and a confidence percentage. Top-level customers are matched against Kompass clients, jobs against Kompass projects.
4. Review the matches and correct any that are wrong by editing the kompass_id column: enter the correct Kompass ID, or clear it where there is no true match. Rows with either side blank are simply skipped on import, so the reviewed file can be uploaded as-is.
5. Return the reviewed CSV to Kompass support, who will import it to create the link records. (If you have API access, you can also upload it yourself to the qbd/customers/import/ endpoint.)
6. You can re-run the comparison afterwards to confirm the remaining unmatched rows are only the records that genuinely exist on one side.

Step 5: Configure Sync Settings and Enable

Once customer reconciliation is complete (or if the company file was empty to start with), configure the sync and enable it:

1. Open the configuration and, under Sync modules, select the modules you wish to sync:
   • Clients: syncs Kompass clients as QuickBooks customers
   • Projects: syncs accepted Kompass projects as jobs (sub-customers) under the billing client's customer
   • Invoices: syncs Kompass invoices as QuickBooks invoices, credit notes as credit memos, and journal invoices as journal entries
2. Projects and Invoices both require Clients to be enabled.
3. Tick the Enable checkbox to activate the connection.
4. Click Save.

Invoices sync when they are approved or posted and have the Sync checkbox ticked. Voiding a synced invoice in Kompass voids it in QuickBooks too. New customers are created in QuickBooks automatically when a project or invoice that needs them syncs.

Step 6: Map Items and Sales Tax Codes (Optional)

For more accurate invoice syncing, additional mappings can be configured in the Admin under QuickBooks Desktop:

• Item (Department) Links: map Kompass departments to QuickBooks service items. A default item can also be set on the configuration as a fallback.
• Sales Tax Code (VAT Rate) Links: link Kompass VAT rates to QuickBooks sales tax codes, with an optional default on the configuration.

Kompass support can provide a listing of the service items and sales tax codes in your company file to map from.

Make sure you will select default item and sales tax code under the Config page.

Good to Know

• The QuickBooks machine needs to be on. Syncing happens through the Web Connector on the machine that hosts QuickBooks. While that machine is off or the Web Connector is not running, changes cannot be delivered; if a sync cannot complete, Kompass notifies the addresses under Notification recipients, and saving the record again once the connection is back retries the sync.
• The sync is one-way. Kompass pushes to QuickBooks; changes made directly in QuickBooks are not pulled back into Kompass. Payment syncing from QuickBooks to Kompass is planned for a future release.
• Attachments are not supported. QuickBooks Desktop's integration interface does not allow attachment upload for any vendor, so invoice files stay in Kompass.
• Single currency. All transactions are posted in the company file's base currency. Multi-currency company files are not supported.
• Name length. QuickBooks limits customer and job names to 41 characters; longer Kompass names are shortened, and colons are replaced with dashes (QuickBooks reserves the colon for its customer:job hierarchy).

If the connection stops working (for example after the QuickBooks machine is replaced or the Web Connector is removed), run the Check QBD connection health action to confirm, then repeat Step 2 to set the Web Connector up again, or contact Kompass support.