This document covers recommended best practices for add-on partners integrating with Xero.
Chart of Account Mapping
Before we begin, a quick explanation of the chart of accounts. In Xero, users will organize data into different accounts. There are 15 different account types organized into the five categories – Assets, Expenses, Equity, Liabilities, and Revenue. Categorizing data in the correct accounts ensures the accuracy of financial statements.
For those integrations creating data in Xero, you will map your application financial data to the chart of accounts in Xero. This mapping streamlines the data flowing into Xero and increases efficiency. While each Xero organization comes with a default chart of accounts, developers should not rely on these default accounts as Xero users often customize or import different account codes from other accounting systems.
After a user has successfully authenticated on Xero, they will be redirected back to your application, this is a perfect time to map a user's chart of accounts. You are free to lay out your configuration screen in a way that makes sense for your application, here are a few dos and don'ts.
Squarespace does this nicely in a two-step process. In step one, they identify if any new accounts need to be created.
In step two, they allow the Xero user to modify how the chart of accounts are mapped. It's a nice balance of guiding the user yet providing flexibility.
Validate your Account Mapping
Xero customers may continue to modify their chart of accounts after they've set up your integration. A best practice is to validate the user's account mappings prior to performing an export. If any accounts are missing, you'll want to notify the user and guide them back to your configuration screen. Once there, they can fix any issues.
Accounts for Payments
Handling payments for invoices requires a chart of account which has payments enabled. You might assume that simply mapping bank accounts would be sufficient, but in some situations, a small business may use a clearing/suspense account to track payments via credit card. Clearing accounts are categorized as a current asset and are enabled to accept payments. You can read a more about how clearing accounts work under handling payment processor receipts. The best approach is to filter your chart of accounts, by the boolean “EnablePaymentsToAccount” and also where the account type is "BANK", allowing the user to map to any account to which payments can be applied.
The requirements around taxes varies between different regions. As the Xero versions for Australia, New Zealand and United Kingdom support filing of tax returns, it is important that default tax rates are used to record taxes on sales, bills and other transactions in Xero. Tax rates created via the API will not work in these regions for the purposes of sales tax reporting/filing.
For other regions, you should ensure the manner in which tax is calculated and recorded is compatible with user expectations and does not deviate from source calculations.
Xero customers using the US version, do not rely on default tax rates. Therefore, developers have some flexibility in how they handle sales tax. For those applications that have tax rate information and wish to create an integration that works for all regions (AU, NZ, US & UK), the best approach is to allow mapping of default tax rates for AU, NZ and UK and dynamic creation of tax rates for US customers. Due to the complexity of sales tax in the US, creating tax rates via the API provides maximum flexibility. Developing a naming scheme for tax rates you create is recommended. For example, "US, CA - 94556", is granular enough for businesses with multiple business locations in a single state.
Squarespace does this nicely by looking at existing tax rates in their system and comparing them to Xero. The user is prompted to create a corresponding tax rate in Xero.
commonSKU takes a different approach and allows you to map component tax rates in their system to existing tax rates in Xero.
You can map one or more commonSKU tax rates to Xero.
If your application only has the total tax amount and not the tax rate, you do have the option to create an additional line item on an invoice. You will need to include a sales tax liability account for this line item. This approach is not valid for customers in AU, NZ and UK.
Synchronizing contacts between two applications can be done either as a one way or bidirectionally; it really depends on the application. For one way syncing, the developer would designate one application as the “source of truth”. Contact updates would always flow from the “source of truth”. The result would be any modification to contacts in the secondary application would be overwritten. While one-way syncing may be simpler to implement, it may not be appropriate for your application.
Bidirectional synchronization of contacts involves comparing any contacts which have changed since the last successful sync and pushing changes to the older contact record. Xero API supports the “If-modified-since” header parameter, which allows you to pull back only the records which are changed since the last successful sync.
You'll want to establish a foreign key relationship between the contact in your application and the one in Xero. You can accomplish this by storing the ContactID returned by Xero in your application. Alternatively you can set the ContactNumber field on a Xero contact with a unique identifier from your application.
Blindly pushing contacts from one system to the other may results in duplicate contacts. Some developers have success matching existing contacts through the contact name or email address. One partner, commonSKU, developed a nice approach of prompting the user to create a new contact or map to an existing contact in Xero. This addresses the issue where a contact has a slightly different name in each application. For example, in your application the contact name could be “Ford”, while in Xero the contact name is “Ford Motor Co.”
commonSKU allows its users to modify their contact mapping as well.
For applications that create or update invoices in Xero there are a few best practices which will ensure this a great experience for your users. The <Url> field on the Invoices endpoint enables a link to be displayed on an invoice within Xero which navigates back to your application. This helps the customers know exactly what application the invoice relates to and provides an easy way to navigate to the relevant information within your application.
Note - the <Url> can not contain the word "xero". Posting an invoice with <Url> set to http://xerotest.mydomain.com would return a validation error.
Example of URL field being used on an Invoice:
The URL on the invoice is formatted as "Go to [xero_application_name]". You can change the name of your Xero application by visiting the application details section in the developer portal.
In addition to linking from a Xero invoice to your application, you can also provide similar functionality in the reverse direction. With the use of a deep link you can create a link from within your application directly to an invoice within Xero.
Deep links enable you to link to Invoices, Contacts, BankTransactions, Reports and other documents within Xero. Using deep links makes it easy for your users to navigate directly to a document within Xero that you're referring to within your application. This is particularly useful for applications that export or sync invoices, contacts and other accounting documents to Xero.
