QuickBooks Online
Kompass syncs Clients, Projects (optionally as sub-customers), and Invoices to QuickBooks Online (QBO) via the Intuit REST API, and can pull payments back from QBO. Before any of that works, a QBO Configuration record must be created and linked to your QBO company through an OAuth authorization flow. This is a one-off setup task for a user with access to the Kompass Admin.
Prerequisites
-
Your Kompass user must have access to the Kompass Admin (
/admin/).
- Your Kompass user must have permissions on the QuickBooks Online models (Configuration, Customer, Project, Invoice, Item Service, Item Department, Tax Code VAT Rate, Custom Field and Payment). If the QuickBooks Online section does not appear in 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 authorize connected apps.
Step 1: Create the Configuration
-
In the Kompass Admin, go to QuickBooks Online → Configurations.

-
Click Add Configuration.

- Select the Org this configuration belongs to. Each Kompass org has exactly one QBO Configuration.
- Leave Enable unticked for now. You will tick it once the OAuth link is in place.
- 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.
-
Sync modules: leave this as it comes, Clients and Projects. You pick the modules in Step 3, once QBO is linked, and turn on Invoices after the item matches are confirmed in Step 4. Invoices cannot be ticked yet: it requires a Default item id, which can only be chosen after linking.

- Leave Default item id at its initial 0 for now: it can only be set after the QBO link is in place, and clearing it prevents the form from saving. Default class id can stay blank. You will set both in Step 3.
- Click Save.
Step 2: Link the Configuration to QuickBooks Online
Linking exchanges an Intuit authorization for a long-lived refresh token. Kompass stores the token against the QBO company's shared connection and links the Configuration to it.
- From the Configurations list, tick the Configuration you just created.
- In the Action dropdown, select Authorize with QuickbooksOnline and click Run.
- You will be redirected to Intuit's sign-in page. Sign in with the QuickBooks Online admin account for the target company.
- Select the company you want Kompass to connect to and click Connect to approve the Accounting scope.
- Intuit redirects you back to Kompass. The callback sets Company id on the Configuration and stores the refresh token on the shared connection 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
- Open the Configuration record and confirm that Company id is populated and Shared connection shows a linked connection with a token.
- 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 the last fallback for invoice lines: Kompass first uses the mapping on the line's Service, then its Department's item mapping, and only uses this default when neither supplies an item.
- Default class id: only needed if your QBO company uses Classes. Select a fallback Class from the dropdown.
- Back on the Configurations list, tick the record, select Test connection from the Action dropdown, and click Run. 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. A history invoice whose item has no match is skipped by the import. For invoices Kompass sends to QuickBooks, a line whose Service has no item mapping first falls back to its Department's item mapping, then to the Default item id from Step 3 if the Department has none either.
- 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.
- 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. Once we confirm, go back to the Configuration, tick Invoices under Sync modules, and click Save.
Other mappings (optional)
Under QuickBooks Online in Kompass Admin, a few more mapping tables control how Kompass data appears in QBO:
- Classes: set a QBO Class on an Item Service or Item Department link. A Class set on an Item Service overrides the Department's Class. The Configuration's Default class id is used only when there is no Item Service or Item Department link.
- Tax Code VAT Rates: required for EU and Canada locales; not used much 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 the Kompass 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.
- Go to QuickBooks Online → Configurations and tick your Configuration.
- In the Action dropdown, choose the transfer you want, then click Run.
- On the confirmation page, check the settings, tick I understand this import may create duplicate records, and click Start import.
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. |
The client and project categories are only a starting point. Choose any category, such as "Other"; you can change categories in bulk after the import.
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 are created as accepted, and their work arrives with the invoice run.
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 and Service within each project, so identical descriptions on different Services become separate quote items. 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 all three transfers in sequence, without waiting for your item matches to be reviewed.
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 recognized and skipped. It can't recognize clients or projects you created in Kompass by hand, so it will create those a second time.
How the sync runs after setup
Most 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 and their Sync checkbox is ticked. Payments are the exception: with the Payments module on, Kompass polls QBO for payments and records them against the matching invoices. Changes propagate in the background. To sync a record immediately, select it on the client, project, or invoice list in Kompass Admin and choose Integrations: trigger sync from the Action menu; the action is available to users with change permission on that list. For an immediate payment poll, use Poll QBO payments now on the Configurations list.
You can also sync a single record from its own page: open the client, project or invoice and choose Sync now from the Actions menu. The sync status icon beside that menu shows whether the record's last sync to QuickBooks Online worked, and the error if it did not. See Syncing records to your integrations.
Troubleshooting actions
The Configurations list has three diagnostic actions:
- 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, credit memos and journals as JSON file: same, for invoices, credit memos and journals.
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.



