The Xero integration for Perk expenses automates the flow of spend-management data between Perk and Xero. Use this article to connect Perk to Xero and configure the Xero integration for Perk expenses, from prerequisites through to disabling the integration if you ever need to.
Before you start
You need an Account admin role with rights to set up users, tax rates, cost objects, expense categories, and integrations.
Because the integration can't create users in Perk, create your users on the People page in Perk before setup, each with the correct email address. The email must exactly match the matching Xero contact's email. At least 1 active Perk user must exist before you can complete setup.
Tip: If you use an HRIS system, connect it to Perk before you set up Xero. New employees then flow into Perk automatically, so you don't have to add them manually.
Warning: Card expenses post as Spend Money Bank Transactions and need a bank account in Xero. Set one up before you rely on export—Perk doesn't check for this during setup, so exports fail at runtime if it's missing.
Warning: Travel expenses also post as Spend Money Bank Transactions and need a bank account in Xero. Perk doesn't check for this during setup either, so set it up first to avoid runtime export failures. Travel expenses also need a transfer account—see Setting up export settings below.
Connecting Perk to Xero
- In Perk, go to Settings > Integrations, then open the ERP integrations tab.
- Find the Xero 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 Xero authentication window opens.
- Log in to Xero and click Allow access to give Perk the permissions it needs.
- Check the Xero hub after authentication. The status reads "Setup incomplete" because import and export settings still need setting up.
Note: If you close the Xero authentication window before you finish, Perk shows a warning prompt. Confirming exit cancels the connection but keeps your company selection, so you can pick up where you left off.
Setting up import settings
Setting up import settings tells the Xero integration for Perk expenses which Xero data to bring into Perk. You complete a four-step wizard from the Import settings card by clicking Set up import.
Caution: 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 Xero accounts to import as expense categories. 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 Xero before you can complete setup.
Warning: Exporting an expense that uses a manually created expense category will fail. You can still create categories manually, but on expenses use only expense categories imported from Xero.
Step 2 — Tracking categories
For each Xero tracking category, choose how it imports:
- As cost objects — employees select these when coding an expense, and Perk uses them for cost allocation and approval routing.
- As a custom field — stored as a custom field on the expense for secondary classification.
Mapping to a custom field creates a new Perk custom field named after the Xero category. You can also choose not to import a category at all (skip it). For each category you import, you choose which option values to bring in — all are selected by default, and at least one must stay selected. Xero supports up to two tracking categories.
Caution: You set the mapping — cost object or custom field — here, and it can't be changed after setup. You can still edit which option values import later, but to change the mapping itself you'll need to contact support.
Tip: At least one tracking category must be mapped as a cost object — cost objects are required for Perk's approval flow, so you can't complete setup without one.
Warning: Exporting an expense that uses a manually created cost object will fail. You can still create cost objects manually, but on expenses use only cost objects imported from Xero.
Step 3 — Tax rates
Review and select which tax rates to import. All rates are pre-selected by default. The list shows each rate's name, percentage, and VAT code. New active tax rates added to Xero later are always auto-imported, and you can deselect any of them later from Import settings.
Warning: Perk doesn't automatically detect or filter sales-class tax rates. Rates with an OUTPUT VAT code are sales-class — they're for invoices, not expenses. If an employee selects an OUTPUT-type rate on an expense, the export fails. Review the list and deselect any OUTPUT-type rates before you continue.
If your Xero organization has no tax rates, you can still continue. Expenses then export with no tax applied.
Step 4 — Contacts
Perk matches Perk users to Xero contacts by email. This step shows how many active Perk users you have, so you can make sure the same people exist as contacts in Xero. No matching happens at this step — Perk matches users during the sync (after the first import) and on every sync after that.
Note: Only existing Perk users can match a Xero contact, and at least one active Perk user must exist to complete setup.
Completing setup
Click Complete setup on the final step to save your settings and queue the first import. When that first import runs depends on the initial Xero data sync — the one-time pull of your Xero data that starts when you connect. If the initial sync is still running when you click Complete setup, the first import starts as soon as that sync finishes; if the sync has already finished, the first import runs on the next nightly sync. Either way, imported data can take a few hours to appear.
Note: There's no on-screen completion notification. The Xero hub shows a single info banner confirming the import has started. Allow a few hours, then check your expense categories, cost objects, and tax rates in Perk.
Setting up export settings
Setting up export settings controls how the Xero integration for Perk expenses sends finished expenses to Xero. You manage these on the Export settings tab in the Xero hub.
Document sending options apply to all expense types and can't differ per type. Perk doesn't restrict file types — documents are sent to Xero as-is, and only characters Xero 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. |
Tip: You can also turn on Export attachments under Settings > Account > Companies > View spend settings > Data export settings. This exports documents as a ZIP file you can access from the export log. This ZIP is for your own records and is not sent to Xero — only the document sending options above control what reaches Xero.
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.
Auto-export is a single configuration that applies to all expense types. If you don't set up auto-export, expenses export only when a finance user clicks Export in Finance > Export.
Export prerequisites depend on how expenses are paid:
- Privately paid expenses export with no extra setup.
- Travel expenses export as Spend Money Bank Transactions. They need a transfer account set in Settings > Expense settings > Travel bookings, which tells Perk which Xero bank account to post against. They also need a bank account set up in Xero. Perk doesn't validate the Xero bank account, so a missing one makes exports fail at runtime.
- Card expenses export to the Xero bank account of the mapped company card (the Xero Credit Card Account); the matching company card must exist in both Perk and Xero.
How sync works after setup
After the first import, the Xero integration for Perk expenses runs a daily sync to pull Xero changes into Perk. Each run is a delta sync — it only looks at records that changed in Xero 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 Xero side won't be picked up. For example, adding a Perk user whose Xero contact already exists won't match them, because nothing changed on the Xero 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 Xero 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 Xero 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 Xero 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 Xero always auto-imports on the next sync, unlike accounts. A tax rate deleted, deactivated, or archived in Xero becomes inactive in Perk (tax rate deletion is detected for Xero). 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 Xero contact that matches a Perk user email is matched on the next sync. When an existing Xero contact is updated, the match is re-evaluated and updates flow to the matched Perk user. A deactivated Xero contact sets the matched Perk user to inactive. A new Perk user whose Xero 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 |
|---|---|---|---|
| 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 Xero. | Name; active or inactive status. |
| 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 Xero; a brand-new tracking category (needs manual mapping first). | Name; option values. |
| Tax rates | New active tax rate (always auto-imports); rate deselected in import settings; rate deleted, deactivated, or archived in Xero; name change; rate (percentage) change. | None — tax rate deletion is detected for Xero. | Name; rate (percentage); status. |
| Users (contacts) | New Xero contact matching a Perk user email; any change on an existing Xero contact (re-evaluates the match); contact deactivated. | New Perk user whose Xero contact already exists and hasn't changed (until you edit the contact); user creation (Perk users aren't created from Xero). | First name; last name; status; contact ID. |
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.
Note: Resources deleted in Xero don't appear in the Edit selection lists, because Perk pulls the current list directly from Xero.
Adding new employees after setup
The sync only re-evaluates a Xero contact when something changes on the Xero side. The recommended order is to add the employee to Perk first, then create the matching Xero contact — the next sync matches them.
If the Xero contact already existed, adding a new Perk user won't trigger a match, because nothing changed on the Xero side. To force a match, open the contact in Xero, change any field — a phone number or a note — and save it. The next sync then matches them.
Caution: The email must be exactly identical on both sides. Email changes aren't synced, so if an email changes you need to update both Perk and Xero manually.
Caution: Each Xero contact must have a unique email address. Email is the match key on both sides, so if two Xero contacts share an email, the wrong Perk user — or the same one repeatedly — can be updated.
Multi-company setups
Xero connections are made per Perk company. Each company has its own Xero organization, its own selections, and its own tracking-category mappings. Use the entity selector at the top of the Xero hub to switch companies and run setup again. Setup starts fresh for each company — previous settings aren't carried over.
Disabling the integration
Disabling the Xero integration for Perk expenses disconnects Xero for a single company. Other companies connected to Xero aren't affected, and your import settings are kept.
- Go to the Xero hub.
- Select the company from the dropdown.
- Click Disable. A confirmation prompt appears.
- Confirm to disconnect Xero for that company.
Confirming disconnects Xero for that company only and returns the Xero card to "Not enabled" for that company. Your import settings persist on the company — they survive disconnect and reconnect — so if you reconnect the same Xero organization later, you don't have to set up imports again from scratch.
Note: Reconnecting the same company to a different Xero organization is a separate case. If you switch organizations, review your import settings, since the saved selections refer to the previous organization's data.
To learn more about this integration, see Xero integration for expenses. To understand how data is exchanged between Xero and Perk,, see Xero and Perk data exchange.
For information about troubleshooting and export-related issues, see Xero integration export errors and troubleshooting.