Set up the Xero integration for Perk expenses

This article covers setting up the Xero integration for Perk expenses: preparing Perk and Xero, connecting, import settings, export settings, and later changes. For what the integration does and how data maps, see Integrate Xero with Perk for expenses. For failed exports and import errors, see Troubleshoot the Xero integration for Perk expenses.

Role: Account admins can perform this task.

Before you start

Getting this groundwork in place avoids failed exports later. You need a Perk account admin role with permissions 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 an email that exactly matches the matching Xero contact's email. At least one active Perk user must exist before you can complete setup. You also need at least one expense account in Xero.

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 and travel expenses post as Spend Money Bank Transactions and need a bank account in Xero. Perk doesn't validate this during setup, so exports fail at runtime if it's missing. Travel expenses additionally need a transfer account — see "Setting up export settings" below.

Connecting Perk to Xero

Connecting Perk to Xero is the entry point for the integration. You pick the company to link, then authorize Perk in Xero through OAuth.

  1. In Perk, go to Settings > Integrations, then open the ERP integrations tab.

  2. Find the Xero card and click Start setup/Manage.

    ERP integrations tab with the Xero card

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

    Company dropdown

  4. Click Enable. A Xero authentication window opens.

    Enable button
  5. Sign into Xero and click Allow access to grant Perk the permissions it needs.

  6. After authentication, you return to the Xero integration setup. The status reads Setup incomplete because import and export settings still need configuring.

    Setup incomplete status
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.

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 Xero accounts to import as expense categories. Accounts are grouped by type, and you have two selection modes:

  • Select all option 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.

Accounts step
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 skip a category and not import 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.

You can skip every tracking category. If none are imported, nothing maps to cost objects, and the Exclude cost objects from export setting is enabled in Settings > Account > Companies > Spend settings > Data export and ERP configuration.

Tracking categories step
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 Customer Care.
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.
Tax rates step

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 of your Perk users still need a matching Xero contact. When every user is matched, it shows the number of active users in Perk instead. Either way, 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.

Contacts step

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: The setup flow tells you that you'll get an email when the first sync completes, and Perk sends that email when it finishes. The Xero setup also shows an info banner confirming the import has started. Once you receive the email, 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 setup.

Export settings tab

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:

  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.

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. These transactions post to Xero as unreconciled (see the overview for why).
  • 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. These also post to Xero as unreconciled (see the overview for why).

Editing settings after setup

You can revisit import settings 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 Customer Care if you need to change it). Changes save immediately. New data then flows in through webhooks, or at the latest on the nightly reconciliation at 00:00 UTC.

Edit import settings

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

  1. Go to the Xero setup (Settings > Integrations > Xero).
  2. Select the company from the dropdown.
  3. Click Disable. A confirmation prompt appears.
  4. Confirm to disconnect Xero for that company.
Disable confirmation

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.

Was this article helpful?