Xero
Invoiced integrates with the Xero accounting system out of the box to supercharge the billing capabilities of Xero. This document describes how to set up the integration and how it works in detail.
Overview
The Xero integration ships with the following capabilities:
- Bi-directional sync with Xero
- New data from Xero is synced once per hour
- Transactions generated on Invoiced post to Xero in real-time
Data Flow
Invoiced | Sync to Invoiced | Sync to Xero | Xero |
Customer | ← | → | Contact |
Contact | ← | | Contact Person |
Invoice | ← | → | Invoice |
Credit Note | ← | → | Credit Note |
Payment | ← | → | Batch Payment |
Foreign Currency Payment | ← | → | Payment |
Convenience Fee | | → | Invoice |
Setup
- In order to begin syncing with Xero first go to Apps → Xero.
- Click on Connect to Xero. You will be redirected to Xero. You will need to sign in to Xero, if you are not already signed in.
- Next you will be prompted to authorize Invoiced access to your Xero organization. Click on Authorize.
- You will be redirected back to Invoiced. Xero is now connected! Now you can configure the accounting sync in order to tell Invoiced how to map the data into your general ledger.
- Change the account mapping and other settings. Click Save
Usage
Once the Xero integration is enabled it will sync data automatically per the data flows that you have enabled.
Writing data from Invoiced to Xero will sync instantly.
Reading data from Xero to Invoiced, such as when a new invoice is available, will sync once per hour. You can see when the last sync happened on the Accounting Sync page. If you wish to run a one-off sync you can click the Sync Now button.
Once the integration is fully configured, new transactions will sync with Invoiced on a going forward basis. The integration does not sync data created prior to the integration being installed. See Importing Data for instructions on how to import transactions prior to installing Invoiced.
Handling Errors
On the Accounting Sync page you will see a Reconciliation Errors table which contains any sync errors that the integration encountered. Each error listed belongs to individual record that could not be synced. The error message is listed next to each failed record. When a record fails to sync it will not be re-attempted unless there is a new operation (i.e. updating the record) that triggers a new sync. You can retry syncing any failed record by clicking the Retry button or you can ignore the error by clicking the Ignore button. Errors will not go away until they are successful or ignored.
Field Mapping
We support setting several optional fields on Xero that do not have a standard Invoiced field. This can be useful if you are first creating invoices on Invoiced and posting to Xero.
These additional field mappings work when a record on Invoiced has a custom field with a specific ID that corresponds to a specific field on Xero. This gives you granular control of the data sent to Xero.
Object Type | Xero Field | Description |
Invoice | xero_lineamounttypes | Amount type (eg exclusive or inclusive) |
Line Item | xero_accountcode | Account Code |
Line Item | xero_itemcode | Item Code |
Line Item | xero_taxtype | Tax Rate |
Line Item | xero_trackingname1 | Tracking Category 1 Name |
Line Item | xero_trackingoption1 | Tracking Category 1 Value |
Line Item | xero_trackingname2 | Tracking Category 2 Name |
Line Item | xero_trackingoption2 | Tracking Category 2 Value |
Tax Rate Mapping
If you are posting invoices from Invoiced to Xero then you have different options for how taxes are synced to Xero.
- Create sales tax line item (Recommended) The invoice will have No Tax amounts and a line item will be created for sales tax pointed to the sales tax liability account you choose.
- Inherit account tax rate The invoice will have Tax Exclusive amount and the sales account default tax rate will be selected.
- Match tax rate by name The invoice will be created in tax exclusive mode. The tax rate selected on Xero will be matched based on the name of the tax rate on Invoiced. If no match is found then an error is generated.
Deposit Account Mapping
You can map the bank accounts in which payments are deposited into in settings > accounting sync > configure > mapping. You can create rules to choose the deposit account for each payment method and currency combination. The deposit account can be any account that is enabled for payments.
The deposit account in Xero must have an associated code, or Invoiced will not be able to map payments to it. You can view and add an account code in your chart of accounts in Xero.
Edge Cases
Here we have documented all of the limitations, nuances, and edge cases to be aware of when using the Xero integration.
General
- Xero has a hard limit of 5,000 API operations per day. If you run into this rate limit then you will have to retry your sync operation later when the rate limit has been reset.
- Xero also has a hard limit of 60 API operations per minute. If you run into this rate limit then the sync will pause for a minute and retry the request. As a result you might find that operations to Xero are temporarily delayed. The integration can use fewer API calls by making sure that you have only enabled the data flows that you need and disable the remaining data flows.
Customers
- It is not possible to reactivate a contact on Xero that was marked inactive on Invoiced. If a customer is marked as inactive on Invoiced and then later reactivated then you must separately restore it on Xero.
Credit Notes
- When a credit note is reapplied on Invoiced, the new application cannot be synced to Xero. You must also modify the credit note application on Xero.
Payments
- When a foreign currency payment from Invoiced is posted to Xero with multiple line items, it will post as multiple payments on Xero because Xero batch payments do not support multi-currency.
FAQs
How long will my Xero organization be connected for?
Your Xero organization will be connected until you click disconnect. If you ever find your account prematurely disconnected then you can reconnect any time in Apps → Xero.
How do I disconnect my Xero organization?
Go to Apps → Xero and click Delete App.
Which Xero organization is connected?
You will find the organization name below the Xero Settings.
How are payments recorded on Xero handled?
Payments applied to invoices on Xero will be synced to Invoiced instantly. You must have auto-sync enabled for 2-way payment sync to work.
What accounts does Invoiced create in my chart of accounts?
You can see the accounts we create here.
How are taxes carried over?
The integration adds all the taxes on the invoice from Invoiced and adds a tax line item to the corresponding Xero Invoice. You can disable this behavior with the Add Tax Line Item setting.
What should I do when I changed my Xero organization?
If you have changed your Xero organization then you will need to reconnect your Xero account by clicking on Reconnect in the Xero integration settings.
Are items synced from Invoiced to Xero?
Currently items from Invoiced are not imported into Xero.
Which invoices from Invoiced are synced to Xero?
All non-draft invoices created after the installation of the integration will be synced. The associated customers and payments will also be synced.
If an invoice originated from Xero and was modified on Invoiced then it will not be synced, although any payments received will still be synced.
What happens if the invoice does not have a due date?
Since Xero requires a due date on all invoices, if an invoice is missing a due date the due date will be set to the invoice date on Xero.
Are the taxes on the synced invoices exclusive or inclusive?
Taxes synced to Xero are exclusive by default.
Are tracking categories supported?
Yes, line item tracking categories can be synced to and from Xero.
Troubleshooting
Below we have documented commonly encountered errors and recommended resolutions. If you are still unable to get your books synced then please contact Invoiced Support for further assistance.
Unauthorized
Unauthorized - Invalid authorization credentials.
If you see this error message then our access token to your Xero account has expired. You need to go to Settings → Xero in order to reconnect Xero.
Organisation is not subscribed to currency
Organisation is not subscribed to currency XXX
Invoiced supports 150+ currencies out of the box with no extra configuration needed. If you are seeing this error message then you need to tell Xero about each currency you operate with in Settings → General Settings → Currencies.