Set up the QuickBooks Online integration

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.

Role: Account admins can perform this task.
Plans: Available on Premium and Pro plans only.

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 dataMaps to in PerkNotes
Chart of AccountsExpense categoryYou choose which accounts to import. All account types can be imported, including bank accounts
ClassCost objectQBO Plus/Advanced only; can be assigned per line item or per transaction
Department/LocationCustom fieldQBO Plus/Advanced only; always at transaction level
Tax ratePerk tax rateUS 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 userMatched by email; the user must already exist in Perk
Credit Card AccountPerk company cardThe 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
Tip: If you use an HRIS integration (such as BambooHR or Workday), sync your employees through that integration first. The QBO employee sync doesn’t assign line managers — you’ll need to do that manually or through your HRIS.
Warning: To export card expenses, you need a transfer account set up before you run your first export. Set this up in Settings > Expense settings > Travel bookings.

Connecting QuickBooks Online

Connect Perk to QBO using Intuit OAuth.

  1. In Perk, go to Settings > Integrations.
  2. Select the Integrations tab or search for QuickBooks.
  3. Find the QuickBooks card and click Start setup/Manage.
  4. 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.
  5. Click Enable. A QuickBooks authentication window opens.
  6. Sign into QuickBooks and click Allow access to grant Perk the permissions it needs.
  7. 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.
Note: You can disconnect QBO at any time without affecting historical data already exported to QBO.

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.

  1. In Perk, go to Settings > Integrations > QuickBooks Online.
  2. Select Set up import.
Warning: Complete all four steps in one session. Settings only save when you click Complete setup on the final step. If you exit partway through, you lose your progress.

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).

  1. Classes are mapped to cost objects in Perk by default.
  2. Departments can be mapped to custom fields, or you can choose not to import them.
Note: Classes and Departments are only available on QBO Plus and Advanced plans. They’re not available on Simple Start or Essentials.
Note: Importing Classes doesn’t auto-assign cost object owners — you need to assign those manually after the import.

Use the table below to work out which steps apply to your QBO setup:

QBO setupWhat to do in Perk
Classes and DepartmentsImport Classes as cost objects; import Departments as custom fields. No extra settings needed.
Classes onlyImport Classes as cost objects. Custom fields aren’t used.
Departments onlyImport 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 DepartmentsWhen 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.
Caution: If your QBO account uses Departments but no Classes, Exclude cost objects from Export must be on. When you don’t map Classes to cost objects, Perk turns it on for you. If it gets turned off, all exports fail. You still need at least one cost object created directly in Perk, because the expense form needs one.

Checking Exclude cost objects from Export:

  1. In Perk, go to Settings > Account > Companies, Select the company and go to View Spend Settings. Scroll down to Data export and ERP configuration.
  2. Tick Exclude cost objects from Export.
Note: This setting controls whether cost object data is included in the QBO export. You still need to assign a cost object to each expense in Perk.

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.

  1. Select the tax rates you want to import.
  2. 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.

Caution: Expenses from employees who aren’t matched to a QBO vendor will fail to export. Make sure all expense submitters are matched before running exports.
Note: The employee sync doesn’t assign line managers. Assign line managers manually in Perk or through your HRIS integration.

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.

Warning: Before exporting card expenses, set up a transfer account in Settings Expense settings Travel bookings.

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.

OptionWhat it sends
Don’t send documentsExpense data only. This is the default.
Send receipts onlyExpense data plus receipts.
Send all documentsExpense data plus receipts and supporting documents.

To set up automatic exports:

  1. Click Set up on the Auto-export expenses card.
  2. Choose a frequency — hourly, daily, weekly, or monthly.
  3. 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 typeWhat happens on sync
AccountsA 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 categoriesA 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 ratesA 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.
UsersA 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 typeEvents capturedEvents not capturedAttributes updatedAttributes not updatedDefaults not imported
AccountsNew 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 ratesNew 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.

ErrorLikely causeFix
Export fails for all expensesEmployees not matched to QBO vendorsMake 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 expensesDepartments only (no Classes) and Exclude cost objects from Export is offTurn on Exclude cost objects from Export in Perk settings
Export fails for specific expensesExpense has multiple cost objects and QBO Assign class is set to one per transactionChange Assign class in QBO to per line item, or make sure each expense has only 1 cost object
Card expenses fail to exportNo transfer account set upSet 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.

  1. In Perk, go to Settings > Integrations.
  2. Select the Integrations tab.
  3. Find QuickBooks Online and select Disconnect.
  4. Confirm the disconnection.
Note: Disconnecting QBO doesn’t affect any historical data already exported to QBO.

Was this article helpful?