Skip to main content
Share Feedback gettimely.com

Troubleshooting: Xero integration

  • Updated

This article is for:

Build
Elevate
Innovate

 

Xero is an online accounting system, that integrates with Timely to help you manage your financial transactions. When you connect Xero to your Timely account, we'll automatically make sure that your Timely invoices, and any associated payments, are synced across to your Xero account. So you only have to enter your sales information in one place! 


In this guide you will learn how to troubleshoot the most common errors faced by Timely customers when using the Xero integration. For information on our frequently asked questions (FAQs), see our help guide Frequently asked questions (FAQs): Xero.

 

 

Timely note: you can check for any alerts or errors by heading to the setup > integrations (formerly add ons) page. Any errors will be displayed at the top of the page. Once an error has been addressed, it will disappear/be hidden after 30 days. If your question or error isn't covered here, please get in touch with us by submitting a Help Form at our Help Centre.

 

 

Troubleshooting Xero error messages 

These are some common error messages that can occur in Timely when using the Xero integration. We've listed how to address those errors below. If you don't see your error message here, get in touch with us by submitting a Help Form at our Help Centre.

 

A Error: The Tax Type field is mandatory. Account code must be specified.

 

This can occur when a clearing account has not been set up, or has been removed or changed. To fix this you'll need to:
 

  • In Timely, go to setup > add ons > Xero (configure) > edit settings
  • Ensure an account has been selected for all your payment types
  • If no account has been selected, you'll get an error message saying "Oops! You'll need to set up a clearing account in Xero". If this happens, follow the on-screen instructions.

 

 

B Error: Payments can only be made against authorised documents.

 

This happens if the invoice was originally synced to Xero as "on account" or unpaid, and the status of the invoice is set to Draft in Xero. You will either need to change the settings for on account invoices in Timely, or approve the invoice in Xero. To change the settings for on account invoices in Timely:
 

  • In Timely, go to setup > add ons > Xero (configure) > edit settings
  • Under status of on-account invoices, update this to approved
  • Click save to apply your changes

 

 

C Error: Payments can only be made against authorised documents. Payment amount exceeds the amount outstanding on this document.

 

Getting these two errors together means that a payment has already been applied to the invoice in Xero. If you want Timely to be the most accurate record of sale, you'll need to delete the existing payment in Xero, apply the payment in Timely and then sync the payment again.

 

 

D Error: Invoice voided

 

This message will appear in your Add-on Integration Errors if an invoice that was created in Timely and synced to Xero was later deleted in Xero. If a Timely invoice is deleted in Xero, you will not be able to sync applied payments for that invoice.

 

 

E Error: Payment type has not been mapped to Xero.

 

This error will occur if the payment type you are trying to apply to an invoice has not been mapped to an account in Xero. To update these settings in Timely:
 

  • Go to setup > integrations (formerly add-ons) > Xero (configure) > edit settings
  • Go to the account mappings tab
  • Under the relevant payment type, select the Xero account from the dropdown menu
  • Click save to apply your changes

 

 

F Error: The existing contact with name customer's name cannot be updated to use new name new name. There is an existing contact with that name.

 

This error occurs when the customer's name in Timely is the same as an existing contact in Xero. The integration won't allow the creation of a duplicate customer record. You will need to adjust the customer's name in Timely (or Xero) or archive/delete that customer in Xero.

 

 

G Error: Xero authorisation has expired. Session has expired. You'll need to renew now.

 

This error may show up in your Add On Integration Errors. To fix this:
 

  • Go to setup > integrations (formerly add-ons) > Xero (configure)
  • Click renew now
  • This will open a window to log in to Xero. Enter your Xero account details and click login
  • Your existing settings, as well as account and payment mappings will be retained
  • Any invoices that did not sync while your Xero authorisation was expired will sync to Xero
     

Only the staff member/administrator that setup the integration will be authorised to Renew the connection. If another staff member attempts to renew the connection, then the authorisation will expire immediately.

 

 

H Error: The contact with the specified contact details has been archived. The contact must be un-archived before creating new invoices or credit notes.

 

You'll need to restore the contact in Xero. See instructions for archiving and restoring customers in this Xero guide . 

 

 

I Error: Bank account status invalid for payment creation.

 

This means that the bank account the payments were synced to no longer exists. It may have been deleted, archived or edited in some way that disrupted the sync. You will need to correct this in Xero and re-map the payments to the correct account.

Related articles