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.
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
- Initial data sync
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 |
- 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
When the Write setting is enabled for convenience fees, the integration will create a convenience fee invoice in Xero. The convenience fee is applied to this invoice, so it does not create a credit in the accounting system. When this setting is enabled, you will be prompted to configure account mapping for the convenience fee invoice line item.
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.
The initial data sync feature allows you to sync data from your accounting system that was created before the integration was installed. You can run the initial data sync after you first install the integration to pick up previous transactions. The initial data sync is optional and is only performed if initiated by you.
The initial data sync can be started by going to the Accounting Sync page and clicking the Initial Data Sync button. Then you can select the type of data you want to sync and the date range for any transactions that will be synced.
You can only select a date range of at most 1 year. However, you can run multiple initial data syncs if you want to get transactions from a greater time period. Syncing more than 1,000 records at a time might not complete. If you need to sync a large volume of data, see Importing Data for instructions on how to import data through a spreadsheet.
And here's a pro tip: if you're fetching invoices or credit notes from the past, don't forget to grab the payments, too. This way, you'll ensure your financial history is complete, with every balance perfectly in place.
Once the initial data sync is complete and you are satisfied with the results, we do not recommend using it again. The ongoing sync of the integration will keep your data up to date automatically.
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.
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 |
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.
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.
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.
-
Invoices
- Late fees will only sync to Xero if the invoice is originally created in Invoiced. Late fees applied in Invoiced will not sync to Xero if you create invoices in Xero.
- Xero supports 2 and 4 digit precision on the invoice line item quantity. If you create invoices in Invoiced with 3 digit precision, you will see a rounding error. You can change your unit cost precision to 2 or 4 digits in Invoiced in settings > accounts receivable.
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.
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.
Go to Apps → Xero and click Delete App.
You will find the organization name below the Xero Settings.
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.
You can see the accounts we create here.
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.
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.
Currently items from Invoiced are not imported into 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.
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.
Taxes synced to Xero are exclusive by default.
Yes, line item tracking categories can be synced to and from Xero.
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 - 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 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.