The Xero integration allows Perk expenses to be exported directly to Xero, helping keep expense data and accounting records synchronized. If an export fails, the issue can appear in different ways depending on the underlying cause.
This article explains common export failure scenarios and how to troubleshoot them using known issues, messages generated by Perk, and validation messages returned by Xero.
Troubleshooting and export failure scenarios
If expenses are not exporting, the most common causes are:
- A Perk user does not have a matching Xero contact (email mismatch)
- A sales-class (OUTPUT) tax rate was selected on the expense
- A required transfer or bank account is missing for card or travel expenses
Review the scenarios below to identify the issue and resolve it.
| Scenario | Cause |
|---|---|
| Contact or email match failure | A Perk user's email doesn't exactly match a Xero contact, so the expense can't post. |
| Duplicate contact in Xero | Xero rejects the export because a contact or record looks like a duplicate. |
| Sync not complete yet | Right after connecting, imports and exports are gated until you click Complete setup on the import wizard. Until then, the integration skips import jobs. |
| Sales-class (OUTPUT) tax rate selected | An OUTPUT or sales-class tax rate used on an expense makes Xero reject it. |
| Missing bank account for card or travel | Card and travel expenses post as Spend Money Bank Transactions and need a bank account in Xero. Without it, exports fail at runtime with no warning in Perk. |
| Missing transfer account for travel | Travel expenses need a transfer account set in Settings > Expense settings > Travel bookings. Without it, the export fails. |
| Manually created category or cost object used | Expense categories and cost objects created manually in Perk have no Xero link, so exports that use them fail. |
| Manually created custom field | A custom field that wasn't imported from Xero has no Xero link, so its value is left off the export instead of failing it. |
| Required field missing | Xero reports a missing required field on the expense. |
| Expired Xero connection | The Xero connection expired or was revoked. |
| Sync seems stuck | The first sync can take a few hours. |
Error messages and what they mean
When an export fails, Perk shows a message based on what Xero or the integration reported. The table below lists the messages you may see and who should act on each. In these messages, the integration name shows as "Xero", and {model} is the specific record involved — for example, a contact, account, or tax rate.
| Message | When it appears | Who should act | Required action |
|---|---|---|---|
| Your expense is missing a required field for Xero: {model}. Please review and retry. | A required field on the expense is missing. | Employee | Add the missing field on the expense, then export again. |
| We couldn't find a matching {model} in Xero. Check your Xero setup. | A referenced record — a contact, account, or category — doesn't exist in Xero. | Admin | Create or import the matching record in Xero, then export again. |
| This expense may already exist in Xero. Check for duplicates before retrying. | Xero sees a duplicate record. | Employee | Check Xero for the duplicate and remove it (or confirm it is intended) before retrying. |
| An invalid value was sent for {model}. Check your Xero setup. | An invalid choice was sent, such as a tracking category or tax rate Xero won't accept. | Employee or admin | Correct the value (for example, use a valid tracking category or a purchase-class tax rate), then export again. |
| An invalid value type was sent for {model}. Check your Xero setup. | A field value was the wrong type. | Employee or admin | Fix the field value on the expense, then export again. |
| Your expense could not be posted to Xero. Please review the data and retry. | Xero rejected the expense with a general provider error. | Employee | Review the expense against Xero's requirements, then export again. |
| Your Xero connection has expired. Please reconnect from Settings. | The Xero connection expired or needs re-linking. | Admin | Reconnect Xero from Settings > Integrations. |
| Too many requests to Xero. Please retry later. | Xero's rate limit was hit. | Retry later | Wait, then export again. No setup change needed. |
| An unexpected error occurred. Our team has been notified. | An internal error that isn't actionable by the user. | Perk | No action needed; contact support if it persists. |
Xero validation errors are handled a bit differently. Two cases get a clearer message; everything else is shown exactly as Xero returns it:
| Message | When it appears |
|---|---|
| The employee could not be matched to a valid Xero user. Please verify the user mapping. | Xero couldn't identify a valid user for the expense (a user-mapping error). |
| Xero rejected the request due to insufficient permissions. Please check the Xero integration credentials. | The Xero connection lacks the permissions it needs. |
| Any other Xero message | Other Xero validation errors are shown word for word as Xero returns them. |
To learn more about this integration, see Xero integration for expenses. To understand how information is shared between systems, see Xero and Perk data exchange.
For setup-related guidance, refer to Set up the Xero integration for Perk expenses.