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, set up 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 (you choose which account types and accounts to import)
- Tax rates (US sales tax rates are supported)
- 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
Perk fetches changes from QBO at least once a day (nightly at 00:00 UTC) and also imports whenever Merge finishes syncing with QBO. Perk can’t control when Merge syncs, so changes in QBO can take a while to appear in Perk. 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 category | You choose which accounts to import. All account types can be imported, including bank accounts |
| 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 are supported. Other regions, such as the UK, may also work, but region-specific tax rules can apply |
| 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.
- Sign into QuickBooks and click Allow access to grant Perk the permissions it needs.
- After authentication, you return to the QuickBooks hub. The status reads Set up import because you still need to set up the import and export settings.
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 Set up 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 you can choose not to import them.
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. When you don’t map Classes to cost objects, Perk turns on Exclude cost objects from Export for you. Create at least one cost object directly in Perk. |
| Neither Classes nor Departments | When you don’t map Classes to cost objects, Perk turns on Exclude cost objects from Export for you. Create at least one cost object directly in Perk. |
Checking Exclude cost objects from Export:
- In Perk, go to Settings > Account > Companies, Select the company and go to View Spend Settings. Scroll down 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. US sales tax rates are supported. Rates for other regions, such as the UK, may also work, but region-specific tax rules can apply.
- 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. Perk exports receipts and attachments with each expense — 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. It also syncs whenever Merge finishes syncing with QBO. Perk can’t control when Merge syncs, so the timing of those updates can vary. 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 sync. 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 turn it off. 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 turn it off. 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 behavior matrix
The same behavior 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 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 Exclude cost objects from Export is off | Turn on Exclude cost objects from Export 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 export Classes on the lines and Departments on the header.
- 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.