Troubleshoot the Xero integration for Perk expenses

Use this article to find out why data from Xero isn't showing up in Perk, or why an expense didn't export to Xero, and how to fix it. It covers how to check sync status, the most common causes of failed exports, and what each export error message means.

Role: Account admins can perform these tasks.

Employees see export error messages on their expenses, and some of those messages need an employee to fix the expense. This article tells you who needs to act so you can ask them. For setup steps, see Set up the Xero integration for Perk expenses.

Checking sync status

The Xero integration for Perk expenses shows what Perk imported from Xero, what failed, and when the next sync runs on the Import settings page. Check it first when data looks out of date.

Reading the import summary

Import settings shows one card for each kind of data Perk imports from Xero: accounts (including company cards), tracking categories (cost objects and custom fields), tax rates, and contacts.

Import summary cards

Each card shows:

The total number of records imported.
The number of records that failed to import, with a link to the failures.
A link to the matching data in Perk.
A link to edit your import settings.

The contacts card shows how many Perk users matched a Xero contact and how many didn't, with a link to Employees.

Fixing import errors

When an import card shows an error, select it to open the Import error logs panel. The panel lists import problems grouped by data type and error type. Each error shows the data type, the record affected (where available), the reason, a suggested action, and a timestamp. When you fix an error, Perk removes it from the list.

The table below lists common import errors. Other errors can appear, so follow the suggested action shown on each one.

Errors you fix as an admin

Error	What it means	What to do
Data mismatch between Xero and Perk	A Perk user's email doesn't match their Xero contact's email, so Perk can't match them.	Update the email in Perk or Xero so both match. Then select Import now to check the error clears.
Account not found	A company card exists in Perk, but Xero has no matching account.	Add the account in Xero, or update the card in Perk. Then select Import now to check the error clears.

Errors you wait out or report

Error	What it means	What to do
Xero or provider issue	Xero (the provider) didn't respond in time.	Wait and try again later. If the error stays, contact Customer Care.
Internal import failure	An import failed for a reason Perk didn't expect. Perk's team is looking into it.	You don't need to do anything.

Refreshing with Import now

Import now refreshes all your Xero data in Perk right away, so you don't have to wait for the next sync. Select it on the import history card after you change something in Xero or Perk. Perk emails you when the import finishes.

After you use Import now, you can't use it again for 1 hour. During that time, the button is turned off and Perk tells you it isn't available yet. Perk also turns it off if your Xero connection doesn't allow it, and tells you why.

Note: Perk sends the same email after Import now as after your first import. Scheduled syncs, including the nightly check at 00:00 UTC, don't send an email. If Import now finishes while Xero is still syncing and there's nothing to import, Perk doesn't send an email.

If the first sync after you connect Xero seems stuck, wait a few hours—the first sync can take that long. Then check the import history, the next sync time, and the Import error logs panel. Fix any errors, and select Import now. If your expense categories, cost objects, and tax rates still don't appear after several hours, contact Customer Care.

Reading import history

The import history table shows the last 5 imports for your company, with the date and time, the number of records processed, the number of errors, and the sync type. Below the table, Perk shows the next scheduled sync time, and a message if syncs are failing. If you need to reconnect Xero, Perk doesn't add failed syncs to the history.

Fixing export problems

An expense can fail to export from Perk to Xero for a few common reasons. Start with these three, which cause most failures: a Perk user with no matching Xero contact, a sales tax rate on the expense, and a missing transfer account for travel expenses.

Problems that don't show a clear message

Problem	Why it happens	What to do
Email doesn't match a Xero contact	Perk matches each user to a Xero contact by email. If the emails differ, Perk can't post the expense to Xero.	Make sure the user exists in both Perk and Xero with exactly the same email. If the Xero contact already existed before you added the user in Perk, edit any field on the contact in Xero, like a phone number, and save it. The next sync matches them.
Sales tax rate on the expense	Xero marks tax rates meant for sales invoices with an OUTPUT VAT code. Xero rejects these rates on expenses.	In Import settings, deselect OUTPUT tax rates. Ask the employee to choose a purchase tax rate on the expense, then export again.
No bank account in Xero for card or travel expenses	Perk posts card and travel expenses to Xero as Spend Money transactions, which need a bank account in Xero. Perk doesn't check for this during setup, so you only find out when you export.	Add a bank account in Xero. Then export again.
No transfer account for travel expenses	Perk needs a transfer account to know which Xero bank account to post travel expenses to.	In Perk, go to Settings > Expense settings > Travel bookings and set the transfer account. Then export again.
Expense category or cost object created in Perk	Perk can't match categories and cost objects you created in Perk to anything in Xero. Exports that use them fail.	Use only categories and cost objects imported from Xero. If one is missing, check your import settings and select Import now.
Custom field created in Perk	Perk can't match custom fields you created in Perk to anything in Xero. Perk leaves their values off the export, and the export still succeeds.	Use only custom fields and values imported from Xero.
Account deleted or archived in Xero	Perk doesn't find out when you delete or archive an account in Xero, so the expense category stays active. Exports that use it fail.	Deactivate the expense category in Perk. Then ask the employee to choose a different category and export again.

For problems that show an error message on the expense, see "Reading export error messages".

Reading export error messages

When an export fails, Perk shows a message on the expense based on what Xero or the integration reported. In the messages below, Xero is the integration name and {model} is the record involved, like a contact, account, or tax rate.

Messages an employee fixes

Message	What it means	What to do
Your expense is missing a required field for Xero: {model}. Please review and retry.	A required field on the expense is empty.	Add the missing field, then export again.
This expense may already exist in Xero. Check for duplicates before retrying.	Xero thinks the expense is a duplicate.	Check Xero for the duplicate. Remove it, or confirm it's meant to be there, then export again.
Your expense could not be posted to Xero. Please review the data and retry.	Xero rejected the expense for a general reason.	Check the expense against Xero's requirements, then export again.

Messages an employee or admin fixes

Message	What it means	What to do
An invalid value was sent for {model}. Check your Xero setup.	Xero doesn't accept a value on the expense, like a tracking category or a sales tax rate.	Correct the value—for example, choose a valid tracking category or a purchase tax rate—then export again.
An invalid value type was sent for {model}. Check your Xero setup.	A field has the wrong type of value.	Fix the value on the expense, then export again.

Messages an admin fixes

Message	What it means	What to do
We couldn't find a matching {model} in Xero. Check your Xero setup.	A contact, account, or category the expense uses doesn't exist in Xero.	Create or import the record in Xero, then export again. If an account was deleted in Xero, see "Account deleted or archived in Xero" above.
Your Xero connection has expired. Please reconnect from Settings.	Xero's connection to Perk expired or needs to be linked again.	Reconnect Xero in Settings > Integrations.

Messages to wait out or report

Message	What it means	What to do
Too many requests to Xero. Please retry later.	You hit Xero's request limit.	Wait, then export again. You don't need to change any settings.
An unexpected error occurred. Our team has been notified.	An internal error you can't fix.	You don't need to do anything. Contact Customer Care if it keeps happening.

Messages from Xero

Xero checks each expense before it accepts it. For two checks, Perk shows its own message. For everything else, Perk shows Xero's message word for word.

Message	What it means
The employee could not be matched to a valid Xero user. Please verify the user mapping.	Xero couldn't find a valid user for the expense. Check that the employee's email matches their Xero contact.
Xero rejected the request due to insufficient permissions. Please check the Xero integration credentials.	The Xero connection doesn't have the permissions it needs. Reconnect Xero in Settings > Integrations.
Any other Xero message	Perk shows it exactly as Xero returns it.