The QuickBooks Online (QBO) integration lets you import master data from QBO into Perk — including accounting categories, tax rates, tracking categories, and employees — and export approved expenses back to QBO. Use this article to connect QBO, import your data, configure export settings, and troubleshoot common errors.
Overview
The QBO integration syncs data between Perk and QBO in two directions. Perk imports reference data from QBO so your team can code expenses correctly, and finance users can export approved expenses from Perk directly into QBO. What Perk imports from QBO:
- Accounting categories from your Chart of Accounts (expense-type accounts only)
- Tax rates (US sales tax)
- Tracking categories: Classes (as cost objects) and Departments/Locations (as custom fields)
- Employees matched to existing Perk users via QBO vendor email addresses
What Perk exports to QBO:
- Private paid (reimbursable) expenses → Expense/Purchase
- Card transactions → Credit Card Charge
- Travel expenses → Expense/Purchase
- Credit notes → Credit Note
Imports run in a daily batch at midnight, please wait for any changes in QBO to sync and check back the next day. Perk connects to QBO using Intuit OAuth, powered by Merge.dev.
How Perk and QuickBooks Online data map
The table below shows how QBO data maps to Perk concepts.
| QBO data | Maps to in Perk | Notes |
|---|---|---|
| Chart of Accounts (expense type) | Expense category | Expense-type accounts only; bank accounts are excluded |
| Class | Cost object | QBO Plus/Advanced only; can be assigned per line item or per transaction |
| Department/Location | Custom field | QBO Plus/Advanced only; always at transaction level |
| Tax rate | Perk tax rate | US sales tax rates only |
| Vendor (with email) | Perk user | Matched by email; the user must already exist in Perk |
| Credit Card Account | Perk company card | The company card must be created in Perk first. |
Before you start
Make sure you have the following in place before connecting QBO:
- Account admin access in Perk
- Admin access to your QBO account
- All employees who submit expenses in Perk already exist as users in Perk — QBO vendor matching won't create new Perk users
- QBO vendors have email addresses — vendors without an email address can't be matched to Perk users
Connecting QuickBooks Online
Connect Perk to QBO using Intuit OAuth.
- In Perk, go to Settings Integrations.
- Select the Integrations tab or search for Quickbooks.
- Find the Quickbooks card and click Start setup/Manage.
- Select the company to connect from the dropdown. The company you're assigned to is selected by default; pick a different one if needed. You must select a company to continue.
- Click Enable. A Quickbooks authentication window opens.
- Log in to Quickbooks and click Allow access to grant Perk the permissions it needs.
- After authentication, you return to the Quickbooks hub. The status reads "Setup Import" because import and export settings still need configuring.
Setting up import settings
After connecting QBO, import your reference data into Perk. Each data type is imported separately — work through the steps below in order.
- In Perk, go to Settings Integrations QuickBooks Online.
- Select Setup Import.
Step 1 — Accounts
Choose which Expense categories come from your QBO Chart of Accounts. Accounts are grouped by type, and you have two selection modes:
- Select the type-level checkbox to import all current accounts in that type and auto-import any future active accounts added to that type later.
- Select individual accounts to import only those. New accounts added to that type later are not auto-imported — you add them manually from Import settings.
The Expense type is fully selected by default. All other types are unselected. You must select at least one account, so you need at least one expense account set up in QBO before you can complete setup.
Step 2 — Dimensions
Dimensions include QBO Classes and Departments (also called Locations, Divisions, or Business Units).
- Classes are mapped to cost objects in Perk by default
- Departments can be mapped to custom fields or do no import
Use the table below to work out which steps apply to your QBO setup:
| QBO setup | What to do in Perk |
|---|---|
| Classes and Departments | Import Classes as cost objects; import Departments as custom fields. No extra settings needed. |
| Classes only | Import Classes as cost objects. Custom fields aren't used. |
| Departments only | Import Departments as custom fields. Turn on Do Not Export Cost Objects in Perk. |
| Neither Classes nor Departments | Turn on Do Not Export Cost Objects in Perk. |
Turning on Do Not Export Cost Objects:
- In Perk, go to Settings Account Companies Select the company View Spend Settings Scroll to Data Export and ERP configuration.
- Tick Exclude cost objects from Export.
Class assignment mode in QBO: QBO lets you assign Classes either per line item or per transaction ("One to entire transaction"). If your QBO account is set to one Class per transaction and an expense in Perk has more than one cost object, the export will fail. To avoid this, either change the Assign class setting in QBO to per line item, or make sure each expense has only one cost object before exporting.
Step 3 — Tax rates
Perk imports tax rates from QBO by their QBO ID.
- Select the tax rates you want to import
- Click next.
Step 4 — Employees
The employee sync matches QBO vendors to existing Perk users by email address. Employees must already exist in Perk before you run the sync.
Setting up export settings
Once your import settings are in place, finance users can export approved expenses to QBO. You can export private paid expenses, card expenses, travel expenses, and credit notes. Receipts and attachments are exported automatically — no extra steps needed.
Document sending options apply to all expense types and can't differ per type. Perk doesn't restrict file types — documents are sent to QBO as-is, and only characters QBO rejects are removed from file names.
| Option | What it sends |
|---|---|
| Don't send documents | Expense data only. This is the default. |
| Send receipts only | Expense data plus receipts. |
| Send all documents | Expense data plus receipts and supporting documents. |
To set up automatic exports:
- Click Set up on the Auto-export expenses card.
- Choose a frequency — hourly, daily, weekly, or monthly.
- Select the Perk user the export runs under. This user appears in the audit trail.
Multi-currency exports: If your QBO account uses multi-currency mode, the posting currency for each expense is controlled by the Posting currency setting in Settings Companies Company Spend company settings Posting currency. If your QBO account is single-currency, expenses always post in your company's base currency.
How sync works after setup
After the first import, the QBO integration for Perk expenses runs a daily sync to pull QBO changes into Perk. Each run is a delta sync — it only looks at records that changed in QBO since the last run, not the full data set. Changes flow on the next daily run. The table below shows how each kind of data behaves. Because syncs are delta-based, a change that doesn't register on the QBO side won't be picked up. For example, adding a Perk user whose QBO contact already exists won't match them, because nothing changed on the QBO contact — see "Adding new employees after setup" for the fix.
| Data type | What happens on sync |
|---|---|
| Accounts | A new account in a type you selected at account type level auto-imports on the next sync. A new account in a type where you only picked individual accounts is not auto-imported — add it manually. If you deselect an account in import settings, it becomes inactive in Perk. An account deleted or archived in QBO is not detected, so it stays active in Perk until you deactivate it manually. A renamed account updates its name. |
| Tracking categories | A new option value in a mapped category auto-imports. A tracking category or option deleted or archived in QBO is not detected, so the matching cost object or custom field stays active in Perk until you deactivate it manually. A brand-new tracking category added in QBO after setup is not auto-imported, because no mapping exists — go to Import settings Edit to map it. |
| Tax rates | A new active tax rate in QBO always auto-imports on the next sync, unlike accounts. A tax rate deleted, deactivated, or archived in QBO becomes inactive in Perk (tax rate deletion is detected for QBO). Deselecting a tax rate in import settings also deactivates it in Perk. Tax rate name and percentage changes sync for selected and auto-synced rates — the next sync updates the name, code, and rate. |
| Users | A new QBO contact that matches a Perk user email is matched on the next sync. When an existing QBO contact is updated, the match is re-evaluated and updates flow to the matched Perk user. A deactivated QBO contact sets the matched Perk user to inactive. A new Perk user whose QBO contact already existed and hasn't changed is not matched automatically — see "Adding new employees after setup". |
Sync behaviour matrix
The same behaviour broken down for debugging and implementation.
| Data type | Events captured | Events not captured | Attributes updated | Attributes not updated | Defaults not imported |
|---|---|---|---|---|---|
| Accounts | New account (auto-imports if you selected its type at the type level); account renamed; account deselected in import settings. | Account deleted or archived in QBO. | Name; active or inactive status. | None — the ERP code edited in Perk doesn't affect export, since an internal ID is used. | None. |
| Tracking categories (cost objects and custom fields) | New option value under a mapped category; option or category renamed. | Tracking category or option deleted or archived in QBO; a brand-new tracking category (needs manual mapping first). | Name; option values. | Mapping type (cost object vs custom field), which is fixed at setup. | Cost object approvers — set them manually in Perk. |
| Tax rates | New active tax rate (always auto-imports); rate deselected in import settings; rate deleted, deactivated, or archived in QBO; name change; rate (percentage) change. | None — tax rate deletion is detected for QBO. | Name; rate (percentage); status. | None. | None. |
| Users (contacts) | New QBO contact matching a Perk user email; any change on an existing QBO contact (re-evaluates the match); contact deactivated. | New Perk user whose QBO contact already exists and hasn't changed (until you edit the contact); user creation (Perk users aren't created from QBO). | First name; last name; status; contact ID. | Email — the match key; update both sides manually. | Approval limits, line managers, and default cost objects — set in Perk, not imported. |
Adding new employees after setup
The sync only re-evaluates a QBO contact when something changes on the QBO side. The recommended order is to add the employee to Perk first, then create the matching QBO contact — the next sync matches them. If the QBO contact already existed, adding a new Perk user won't trigger a match, because nothing changed on the QBO side. To force a match, open the contact in QBO, change any field — a phone number or a note — and save it. The next sync then matches them.
Editing settings after setup
You can revisit Import settings Edit at any time. You can change which accounts, tracking-category option values, and tax rates import. You can't change a tracking category's mapping — cost object or custom field — after setup, because that's permanent (contact support if you need to change it). Changes save immediately, but new data flows only on the next daily sync.
Troubleshooting export errors
If an export fails, use the table below to identify the cause and fix it.
| Error | Likely cause | Fix |
|---|---|---|
| Export fails for all expenses | Employees not matched to QBO vendors | Make sure all expense submitters are matched to a QBO vendor. They should have the same email address in Perk and QBO |
| Export fails for all expenses | Departments only (no Classes) and Do Not Export Cost Objects is off | Turn on Do Not Export Cost Objects in Perk settings |
| Export fails for specific expenses | Expense has multiple cost objects and QBO Assign class is set to one per transaction | Change Assign class in QBO to per line item, or make sure each expense has only 1 cost object |
| Card expenses fail to export | No transfer account set up | Set up a transfer account in Settings Expense settings Travel bookings |
Good to know
- Classes and Departments are only available on QBO Plus and Advanced plans.
- Credit notes don't export Class data — this is a QBO platform limitation.
- Vendors without email addresses can't be matched to Perk users.
- Cost object owners must be assigned manually after importing Classes.
- Disconnecting QBO doesn't affect historical data already exported.
Disconnecting QuickBooks Online
You can disconnect QBO at any time from your integration settings.
- In Perk, go to Settings Integrations.
- Select the Integrations tab.
- Find QuickBooks Online and select Disconnect.
- Confirm the disconnection.