Troubleshoot your Xero integration
Lesson 12 of 12 8 min read
A routine for finding out why something didn't reach Xero or posted wrongly, and fixes for the problems you're most likely to meet.
When finance says "this invoice isn't in Xero" or "this posted to the wrong account", you want to find the cause in minutes, not hours. In this lesson you'll learn a routine for tracing any Document to Xero, and the fixes for the most common problems.
Start with the basics
If nothing is reaching Xero at all, check these first:
- Activation on the Integration is enabled.
- Each configuration is set to the right direction: Send to create records in Xero, Receive to read from it.
- A Mapping exists from the source to your Xero Integration, it's enabled, and its filters (customer, tags and so on) match the Documents you expect.
- The Xero connection is still valid. Credentials can expire or be revoked if settings change in Xero, and then you'll need to reconnect.
Trace a single Document
- Find the Document in Supply Lens and open it with the magnifying glass.
- Check its status.
Completemeans it was processed to at least one Mapping.Failedmeans an error was thrown.Readymeans its Mapping isn't automatic and it's waiting for someone to process it. - Click Logs. On a failed Document, the logs contain the message that explains why.
- Check its Target Data.
Pendingis waiting for the next run,Sentreached Xero,Faileddidn't send (check the logs), andCancelledmeans Target Data with the same reference already existed. - If it was sent, find it in Xero by its reference and compare.
Common problems and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| A supplier bill fails | A line's tax code has no Xero tax type | Cross-reference the tax code to a Xero tax type |
| A supplier bill fails | No account from lineAccountCode or lineAccountCodeMap | Set lineAccountCode or add a map entry |
| A foreign-currency bill fails | useDocumentCurrencyRate is on and the Document has no rate | Get the rate onto the source Document, or turn the setting off |
| A journal fails | A line matched nothing in lineAccountCodeMap | Add a route for that kind of line, including the balancing line |
| A journal fails as unbalanced | The journal didn't sum to zero | Contact Support about the balance-journal set-up |
| Invoices aren't marked as sent | Status is DRAFT | Set the status to AUTHORISED if finance agrees |
| A line posted to the wrong account | A tag map matched an earlier entry | Check the order of the map; the first match wins |
| A new supplier contact appeared in Xero | No Xero identifier on the Party, and the name didn't match | Add a Xero identifier to the Party; merge the duplicate in Xero |
| An invoice is in Xero twice | Two connections post the same records | Agree which connection owns them and switch the other off |
| Invoices from Xero aren't imported | Status or contact filter, or the invoice predates receive.setupDate | Check receive.includeInvoiceStatuses, receive.includeContactNames and the setup date |
Fix and resend
Once you've corrected the setting:
- If the Document already has Target Data, set that Target Data to
Cancelled. Otherwise the duplicate check will cancel the new one. - Reprocess the Document (or its Source Data).
- Run the Integration with Run Send, or wait for the schedule.
- If a wrong record already reached Xero, ask finance to void or delete it there.
If the Document's data itself is wrong, you can edit it: open it, click the three dots, then the
pencil Edit button, make the change and click SAVE. SHOW PATCH shows what you changed.
A Complete Document needs its Target Data set to Cancelled before you can reprocess it.
Don't fix it only in Xero
If you correct a posting by hand in Xero but leave the setting wrong, the next Document will post the same way. Fix the cause in Supply Lens first.
When to contact Support
If you're stuck, email support@supplylens.co.uk with your Integration ID, the Document reference and what you expected to happen.
Hilltop's surcharges go missing
A week after go-live, Hilltop's bookkeeper can't find a café's invoice. The implementer finds the
Document Complete, but its Target Data is Failed. The logs show an error from Xero about the
surcharge account code, which finance had archived the day before. She updates
adjustmentLineAccountCodeForCharges to the new code, sets the failed Target Data to Cancelled
so the duplicate check won't block the resend, reprocesses the Document and clicks Run Send.
The invoice appears in Xero.
Recap
- Check Activation, configuration direction, Mappings and the Xero connection first.
- Trace a Document through its status, logs, Target Data and the Xero record.
- Most failures are a missing account route, an unmapped tax code or a missing currency rate.
- Cancel existing Target Data before reprocessing, so the duplicate check doesn't stop the resend.
- Fix the cause in Supply Lens, not just the record in Xero.
Quick guides for this topic
Your progress is saved in this browser. Create a free account to keep it everywhere, take quizzes and earn certificates.