Troubleshooting | Xero integration

get in touch with us by submitting a Help Form at our Help Centre These are some of the most common errors or questions we get about the Timely/Xero integration and some tips for managing them.

If your question, or error, isn't covered here, get in touch using the link below this article!

1. Troubleshooting Xero error messages.
2. My invoices aren't syncing to the correct customer in Xero.
3. I am using Vend, but want to integrate Timely and Xero.
4. I want to sync my historic invoices to Xero.
5. I want to disconnect Xero from my Timely account.

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.

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:

1. In Timely, go to Setup > Add ons > Xero (Configure) > Edit Settings.
2. Ensure an account has been selected for all your payment types.
3. 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 or check out the 'How to set up the Xero integration' article in the Related Articles section below.

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:

1. Go to Setup > Add ons > Xero (Configure) > Edit settings.
2. Under Status of on-account invoices, update this to Approved.
   
3. Click Save to apply those changes.

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.

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.

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:

1. Go to Setup > Add ons > Xero (Configure) > Edit Settings.
2. Go to the Account Mappings tab.
3. Under the relevant payment type, select the Xero account from the dropdown menu.
   
   
4. Click Save.

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.

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:

1. Head to Setup > Add ons > Xero (Configure).
2. You'll see the below alert. Click Renew Now.

1. This will open a window to log in to Xero. Enter your Xero account details and click Login.
2. Your existing settings, as well as account and payment mappings will be retained.
3. 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.

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. Check out the steps for archiving and restoring customers  in this Xero guide . 

Account code '<code>' is not a valid code for this document.

This usually means the wrong Xero account has been mapped to the gift voucher liability account under the Xero settings on Timely. Read this  help doc to correctly set up the liability account.

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.

My invoices aren't syncing to the correct customer in Xero

Behind the scenes we use a  Xero ID to connect the record from Timely to the same customer in Xero. This means that once a customer record is created from an invoice in Timely, any further invoices for this customer will be matched to the existing record. 

A customer record in Timely will only have a Xero ID if the customer was imported into Timely from Xero (via  Customers > Import customers > Import from Xero) or they have an existing invoice from Timely that has already been synced to Xero. 

If you notice that the wrong contact in Xero is linked to the Customer in Timely, this can be updated from our end.

If you locate the Contact in Xero and copy the URL in the navigation bar, you will be able to see the XeroId:

You can then send a screenshot, or a copy of that link and get in touch with us by submitting a Help Form at our Help Centre.

I am using Vend, but want to integrate Timely and Xero

You'll need to integrate Xero with Vend instead of with Timely. There is a  video on Vend's website which explains how to do this. 

The process will then work like this:

1. You add your appointments in Timely.
2. When you're read to take payment at the point-of-sale, click Take payment in Timely.
3. A sale is then raised and transacted in Vend.
4. Your end-of-day till balances are then pushed from Vend to Xero.

Note: If you've already set up a Timely/Xero integration, you'll need to disconnect this before integrating with Vend.

I want to sync my historic invoices to Xero

If you have been using Timely on its own prior to connecting to Xero then you may have existing invoices in Timely that you want to connect to Xero. 

We don't automatically sync historic invoices to Xero when you enable the integration. There are a few reasons behind this; the main reason being that this could cause a bit of a mess with your existing accounts, especially if you have been using Xero separately and have already entered those sales in to Xero manually.

However, if you do want those historic invoices to be synced to Xero, you can sync these manually. That way you have control over which historical invoices are synced to Xero and which aren't:

1. View the invoice (see the help article).
2. At the top of the invoice, you'll see a yellow box with two options: "Settings" or "Sync now":
3. Choose the Sync now option and Confirm the prompt.
4. The invoice will be synced to Xero - you can then use the View invoice link to open it in Xero directly.

I want to disconnect Xero from my Timely account

If you no longer want your invoices automatically syncing from Timely to Xero, you can easily disconnect Xero from your Timely account:

1. Head to Setup > Add ons.
2. Click Configure for Xero.
3. Click Edit settings.
4. Click the red Disconnect button.