When reviewing an integration in order to certify it as an official Xero connected app, the team reviews a number of aspects. These are to ensure that the integration will work as well as possible for as many Xero users as possible, and support issues for everyone are kept to a minimum.
In this guide, we have detailed a number of aspects that prospective partners should consider before putting their integration forward for review.
The Xero product is available in versions for Australia, New Zealand, United Kingdom and the United States of America. For customers in other regions, a 'Rest of World' version is available.
Each version has slight differences, but the primary difference is in the support of region specific sales tax. If you wish to support customers from all regions that Xero provides versions in, you need to be prepared to have tested your integration for compatibility, particularly if your integration creates sales or purchases transactions in Xero.
As the Xero versions for Australia, New Zealand and United Kingdom support filing of tax returns, it is important that provided system or default tax rates are used to record taxes on sales, bills and other transactions in Xero.
For other versions, you should ensure that the manner in which tax is calculated and recorded is compatible with user expectations and does not deviate from source calculations.
If the Xero organisation your application connects to operates in a base currency other than that of your own application, or the organisation is on a price plan with multi-currency features, you should ensure that your application will correctly handle this scenario, or raise an error to the user when they attempt to connect.
If you intend to provide service to customers around the world, but you are unable to provide 24x7 customer support in the same manner as Xero, it is important to communicate hours or support availability, ideally on your support/help page.
It is important that you select the correct type of API application to connect your software app to Xero - this ensures that the connection is made in the most secure way possible, and the user has the best possible experience connecting the application. This guide outlines the correct application type, but feel free to ask if you are in any doubt.
Make sure the following details relating to your application are correct:
An official Xero connected app should use an API application that provides long term access (the user should not have to log in to Xero and authenticate every time they want to pass data to or from Xero). In the vast majority of cases, this should be a Partner API application. Sometimes it is necessary to use a private application, for example if the integration is with a desktop or server based app, but this is the exception.
In some very specific cases short term access is more prudent. For example, applications that are performing a once-off data sync or migration which can be completed within a 30 minute window.
If you wish to be listed as a Xero connected app, and have any doubts as to which application type to use, contact the API team before you start coding!
For Partner API type applications, ensure tokens are being refreshed correctly by authenticating a connection and then waiting for more than 30 minutes before performing an action which will generate an API call. If the API call is successful, we can be sure token refreshing has been implemented.
There are a number of ways in which an API application that has been authorised, can have that authorisation revoked outside of the application itself. These are detailed in our OAuth issues page.
An application attempting to make an API call may get a 401 http error response with an OAuth error as detailed in the above link - this should ideally be handled by a warning and prompt to re-authenticate the API connection.
An application should never request a users Xero login details within their application - the OAuth authentication system should always be used to connect to their Xero data, using the appropriate application type (see above).
There should be a setup screen / view when a user has connected to Xero displaying the following:
If your integration needs to create data in Xero, it is likely you will need users to select one or more account codes to be associated with line items. Developers should never assume a default value as customers can create custom codes or import quite different account code structures from other accounting systems.
This should be a drop-down list of accounts, as populated by the Accounts endpoint.
Ensuring line details are coded to an account saves users time and allows documents to be created at statuses other than 'draft'.
When applying payments to invoices or creating spend/receive money transactions, an account to which this monetary transaction is to be coded needs also to be mapped, in addition to the general ledger account associated with the line item, so the user will need to configure at least one default payment account.
A drop-down list should only be populated with accounts that can be used to apply payments, which will be those that contain one (or both) of the following elements in a response from the Accounts endpoint.
Errors happen - users remove mapped accounts, temporary connectivity issues disrupt integrations, and dozens of other potential problems might surface. It is essential to find a way in your integration to provide an indication to users that an error has taken place.
Virtually every error message received from the API contains details of the reason for the error. Parsing this into a response to be shown to the user will allow them to self-serve issue resolution or at the very least, quickly find help in order to do so, with minimum customer frustration.
This could be an inline message as data is being sent across, or in the case of integrations with scheduled / background data synchronisation, ensuring that messages are communicated to users or visible in the integration setup page will keep everyone happy.