QuickBooks Online

Kompass syncs Clients, Projects (optionally as sub-customers), and Invoices to QuickBooks Online (QBO) via the Intuit REST API. Before any of that works, a QBO Configuration record must be created and linked to your QBO company through an OAuth authorisation flow. This is a one-off setup task for a Kompass Admin with access to the Admin site.

Prerequisites

  • Your Kompass user must have access to the Kompass Admin site (/admin/    ).

  • Your Kompass user must have permissions on the Quickbooks Online models (Configuration, Customer, Project, Invoice, Item Service, Class, Tax Code VAT Rate, Custom Field). If the Quickbooks Online section does not appear in the Kompass Admin sidebar, contact Kompass support to have the permissions added to your group.
  • You must be an admin on the QuickBooks Online company you intend to connect, with permission to authorise connected apps.

Step 1: Create the Configuration

  1. In the Kompass Admin, go to Quickbooks Online → Configurations.

  2. Click Add Configuration.

  3. Select the Org this configuration belongs to. Each Kompass org has exactly one QBO Configuration.
  4. Leave Enable unticked for now. You will tick it once the OAuth link is in place.
  5. Set the remaining fields as needed:
    • Notification recipients: set this to your own email address so you receive sync error notifications. Add more addresses as needed.
    • Project customers: tick this. Recommended. It creates a QBO sub-customer (Job) under the billing client for each Kompass Project, giving you project-level visibility in QBO.
    • DocNumber Template, Project/Sub-customer DisplayName Template, Client DisplayName Template: templates controlling how Kompass records appear in QBO. The defaults work for most customers.
    • Locale: USA, EU, or Canada. This affects whether per-line tax codes are sent; the USA does not use them.

  6. Sync modules: leave this as it comes, Clients and Projects. You pick the full set in Step 3, once QBO is linked. Invoices cannot be ticked yet: it requires a Default Item ID, and that dropdown only populates after linking.

  7. Leave Default Item ID and Default Class ID blank for now: their dropdowns only populate after the QBO link is in place. You will set them in Step 3.
  8. Click Save.

Step 2: Link the Configuration to QuickBooks Online

Linking exchanges an Intuit authorisation for a long-lived refresh token that Kompass stores against the Configuration.

  1. From the Configurations list, tick the Configuration you just created.

  2. In the Action dropdown, select Authorize with QuickbooksOnline and click Go.

  3. You will be redirected to Intuit's sign-in page. Sign in with the QuickBooks Online admin account for the target company.
  4. Select the company you want Kompass to connect to and click Connect to approve the Accounting scope.
  5. Intuit redirects you back to Kompass. The callback populates Company id and Refresh token on the Configuration automatically, so no copy-paste is required.

If the redirect fails or you are returned to an error page, the most common cause is signing in as a user who is not a QBO admin on the target company. Start the action again.

Step 3: Set defaults, enable, and test

  1. Open the Configuration record and confirm that Company id and Refresh token are now populated (they will no longer show the <will be extracted...>     placeholders).
  2. Now that QBO is linked, set the fields that depend on it:
    • Default Item ID: select a QBO Product/Service from the dropdown. This is used on invoice lines whose Kompass Service has no specific Service-to-Item mapping.
    • Default Class ID: only needed if your QBO company uses Classes. Select a fallback Class from the dropdown.
  3. Sync modules: now choose the modules you want to sync. Clients, Projects, and Invoices is the usual selection. Projects and Invoices both require Clients, and Invoices requires the Default Item ID you have just set.
  4. Tick Enable and click Save.
  5. Back on the Configurations list, tick the record, select Test connection from the Action dropdown, and click Go. A success message confirms that Kompass can authenticate against QBO and fetch company info.

If the test fails with a token error, re-run Authorize with QuickbooksOnline. Intuit issues a new refresh token each time and Kompass stores it automatically.

Step 4: Map your QuickBooks items to Kompass services

Before any data moves between Kompass and QuickBooks Online, each QuickBooks item (Product/Service) needs to be matched to a Kompass Service. Kompass uses these matches to bring in your invoice history and to put the right item on every invoice it sends to QuickBooks. If an invoice uses an item that hasn't been matched, that invoice can't be transferred.


  1. Export your item list from QuickBooks Online. In QuickBooks, open Settings ⚙ → Products and services. Set the filter Status to All, so inactive items are included as well as active ones. Then use the Export icon to download the list to Excel.
  2. Send the file to your Kompass onboarding contact. We'll set up the matches for you and confirm when it's done.

Include inactive items. Your past invoices may use items you've since made inactive in QuickBooks. These still need a match, or those invoices can't be brought into Kompass. If you no longer offer one of these services, give it an end date in Kompass after it's matched. That keeps it on your history but stops it being used for new work.

One Kompass Service per item. Each Kompass Service can be matched to only one QuickBooks item. If two items should land on the same kind of work, create a separate Kompass Service for each one.

IMPORTANT: Wait for our confirmation before you turn on the Invoices sync module or ask us to import your QuickBooks history.


Other mappings (optional)

Under Quickbooks Online in Admin, a few more mapping tables control how Kompass data appears in QBO:


  • Classes: map Kompass Departments to QBO Classes. A Class set on an Item Service overrides the Department's Class, and the Configuration's Default Class ID is the final fallback.
  • Tax Code VAT Rates: required for EU and Canada locales; not much used in the USA.
  • Custom Fields: optional.
  • Customers: manual link records between Kompass Clients and existing QBO Customers. Usually not needed, because Kompass creates QBO Customers automatically.

Step 5: Transfer your QuickBooks data into Kompass

You run the transfer from Admin in two parts: first your customers, then your invoices. Each part runs in the background, and when it finishes the results are emailed to you. Make sure your Kompass user account has an email address, or the transfer won't start.


  1. Go to Quickbooks Online → Configurations and tick your Configuration.
  2. In the Action dropdown, choose the transfer you want, then click Run.
  3. On the confirmation page, check the settings, tick I understand this import may create duplicate records, and confirm.

5a. Customers (clients, contacts and projects)

Choose Import customers from QBO (clients, contacts, projects). You can run this as soon as Step 3 is done. Click Run. A new screen will appear titled Run qbo_import_customers.


Field What to choose
Client category The category every transferred client gets. You can change individual clients afterwards.
Project category The category every transferred project gets.
User The person recorded as creator of every transferred record. It defaults to you.
I understand this import may create duplicate records Tick to confirm you've read the warning above.

Please don't worry much about the client and project categories. You can easily add a random one like "Other" or the one from the list you think is more prominent. These categories can be easily batch changed after importing.

Click Start import. You're returned to the Configurations page, and a message confirms the run has been queued and which email address the results will go to. QuickBooks customers become Kompass Clients, their contact details become Contacts, and sub-customers (jobs) become Projects. The projects stay as proposals until the invoice run brings in their work.


5b. Invoices (quote items and invoices)

Run this only after we've confirmed your item matches from Step 4, and after the customers run has finished. Choose Import invoices from QBO (quote items, invoices). The screen is titled Run qbo_import_invoices.


Field What to choose
Aggregate by How invoice lines are grouped into quote items. Description (the default) creates one quote item per distinct line description. Service creates one per Kompass Service. If you're unsure, leave it on Description.
Include customer memo Tick to copy each invoice's customer memo into the Kompass invoice.
Po confirmation Only if you record PO numbers in QuickBooks. It's the confirmation given to projects that carry one. Otherwise leave it blank.
User As for the customers run.
I understand this import may create duplicate records Tick to confirm.

Click Start import. Each invoice is placed on the Kompass project for the QuickBooks job it was billed to, and the matching quote items are created and marked as accepted.


If a red message appears instead, such as Run the customers … import first or Run the services … import first, Kompass has found that the customers run or the item matches are missing. Nothing has been transferred. Get in touch and we'll sort it out.


IMPORTANT: Use the two transfers above, not "Import everything". "Import everything" runs the invoice transfer straight after the customers, before your item matches are checked.

Send us the emailed results. Some invoices may be skipped. The two usual reasons are an item that still has no match, or an invoice billed to a main customer rather than a job, which leaves Kompass no project to put it on. Forward the email to your onboarding contact and we'll help you resolve them.

Running a transfer again is safe for anything it has already brought across: those records are recognised and skipped. It can't recognise clients or projects you created in Kompass by hand, so it will create those a second time.

How the sync runs after setup

Sync is push-only, Kompass to QBO. Clients sync when they change in Kompass; Projects sync as sub-customers if Project customers is enabled; Invoices sync once they reach the Approved, Posted, or Voided state. There is no manual "sync now" button: changes propagate in the background.

Troubleshooting actions

The Configurations list has three further actions for diagnostics:

  • Get QBO customers as JSON: dumps the QBO Customer list as JSON, useful for matching existing QBO records to Kompass Clients.
  • Get QBO jobs (sub-customers) as JSON: same, for sub-customers.
  • Get QBO invoices as JSON: same, for invoices.

Sync errors are emailed to the addresses listed in Notification recipients. If the refresh token is ever invalidated (for example, if someone disconnects Kompass from inside QBO), re-run Authorize with QuickbooksOnline to restore the link.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us