Add-on certification – checklist
When reviewing an integration in order to certify it as an official Xero Add-on, 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.
Xero versions you support
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 24×7 customer support in the same manner as Xero, it is important to communicate hours or support availability, ideally on your support/help page.
Choose the right type of application
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:
- Email address of developer: As this is the email address associated with the application, it is important this is active and not a personal email address of the developer. For partner API applications we generally recommend this is set to a generic email address (eg: firstname.lastname@example.org) so you will continue to receive important notifications from us, even if a staff member leaves. Set at api.xero.com.
- Self-signed expiry date: (for private and partner API applications) We generally recommend this is set at least one year to expiry, but preferably not set too far in the future (max 2 years) so developers come back to update this regularly enough they are still familiar with the process. The current value can be viewed, and certificate updated at api.xero.com.
- Application name: To avoid confusion, the application name cannot contain the word Xero, and must reflect the name of the website or application. The current value can be viewed/updated at api.xero.com.
- User agent: The user agent string set in API calls must be similar to the application name. This allows Xero staff to easily & quickly identify the source of any problem API calls from our logging applications. This value is set within the code of the connecting application, but the current user agent value can be viewed in the API history by viewing an API call record.
Long term access
An official Xero Add-on 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 Add-on, and have any doubts as to which application type to use, contact the API team before you start coding!
Partner apps: check token renewal
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.
Handle Revoked Access
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 Add-on 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:
- What the current connection status is
- The name of the organisation in Xero that has been connected to
- An option to disconnect/reconnect (particularly if the connection is no longer active)
- Any default setup values the user might be required to configure (account codes, sync preferences, tax rate mappings etc)
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’.
Payment account mapping
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.
- <Type>BANK</Type> (A bank type account)
- <EnablePaymentsToAccount>true</EnablePaymentsToAccount> (an account that has the ‘enable payments to this account’ option enabled)
Error handling & display
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.