Each integration with Xero is unique and needs to meet a variety of standards, some of these are common across all integrations. This document explains the common criteria that all apps need to meet to certify with Xero. They indicate a minimum, and depending on the functionality of your app, other specific criteria may apply.
Please take the time to ensure your integration fulfills the relevant checkpoints below. We will review your integration against the checkpoints during the certification process.
If you’re stuck, please try to seek help from our developer forums, many developers have been through this process before. If you need further help, please fill in our developer support form to get in contact with us. Or, reach out to your developer evangelist.
The application name must reflect the go-to-market name of your app or product and shouldn’t include the word Xero. The name can be viewed/updated by going to My Apps.
Ensure you implement a setup page that allows users to connect to Xero and manage their settings for the integration. Ideally this should be made possible without assistance from your support or onboarding team.
Do’s:
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 to let users know an error has taken place, within your integration.
Virtually every error received from the API contains details of the reason for the error. Using the information as part of the message you present to the user will allow them to resolve the issue themselves or at the very least, quickly find help in order to do so, with minimum customer frustration. You will want to consider the best way to present messages depending on the way your integration works i.e. instant notifications for real time syncs versus logs on the Xero integration page for scheduled or overnight syncs.
Some apps find that having a page for users to see logs and error messages is helpful, see further below for more information.
Using the offline_access scope is a requirement for certification. Using this scope means you will be able to get a refresh token and so can maintain an offline connection. We require this because it means connections will stay in place over time, this gives us a better understanding of the status of your integration, it informs the app partner program and it will create a better user experience for customers.
Xero has several limits, you can read about them in our documentation. Please read that documentation to understand the different types of information provided in headers relating to limits. You should make sure that you’ve implemented effective ways to work within these limits.
You should request the minimal scopes that you require to fulfil the intended use cases of your integration. Unexplained or ambiguous use of scopes will not be allowed. If not all users are using the same set of scopes, you’ll need to explain this during the review. Some apps also decide to build in a ‘consent screen’ to better explain the usage of the Xero API
Post-certification, any major changes to use cases and scopes should be relayed to your developer evangelist so they can assist you with ensuring the app meets requirements.
We’re asking all apps to implement Sign in with Xero. This means you’d allow users to sign in to your app with their Xero account. It's simple and secure as it leverages security features including two step authentication, anomalous login detection, email address verification and more. You can check out our Sign in with Xero information page for more details.
We’re asking all apps to build a Sign up with Xero flow. Implementing this will enable you to create a seamless app adoption experience. Users will be able to provision an app trial directly from the marketplace that’s pre-populated with their Xero data. You can check out our Sign up with Xero information page for more details.
The modified after parameter is useful to introduce efficiencies by getting only records created or modified since the timestamp you specify. Using this will ensure you’re only getting back records that you need your attention, rather than having to work through a large amount of historic records.
When you retrieve multiple records, like invoices, some detail is omitted for performance. For example with invoices, only a summary of the contact is returned and no line details are returned - this is to keep the response compact. The full details will be returned when you retrieve an individual record, either by specifying it’s ID, or alternatively by using the optional paging parameter to retrieve multiple records.
To utilise paging, append a page parameter to the URL e.g. ?page=1. If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g ?page=2 and continuing this process until no more results are returned. By using paging all the line item details for each invoice are returned which may avoid the need to retrieve each individual invoice, but it also ensures you will not hit a timeout by retrieving too many invoices in one call.
Webhooks allow you to subscribe to certain events that happen in Xero. For now webhooks are available for contact and invoice events. If you plan to poll Xero to keep contact and invoices updated in your app you’ll need to use webhooks to sync data instead.
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 on invoices, purchase orders etc. If you only read data from Xero then this checkpoint is not applicable.
You should never assume a default value as customers can create custom codes or import quite different account code structures from other accounting systems. We have details about how best to approach this in our Integration Best Practices Guide.
If your product handles multi-currency you’ll need to handle any discrepancies in registered currencies between your product and Xero. Currencies must be registered in Xero by the user. You can read a list of the registered currencies from the currencies endpoint.
You can use a PUT call to add missing currencies to Xero on the users behalf. It’s up to you how you design this process and whether you notify the user. It is not possible to remove currencies from an organisation once they've been added.
You may also want to consider checking if the organisation is able to use multi-currency during the initial connection to your app.
If you are working with invoicing you will need to investigate whether your app and Xero handle rounding differently. If your product creates items in Xero such as invoices, it’s important to confirm that totals match. Each line item in Xero allows specifying quantity, unit price, tax rate and discount amount/percentage which are calculated in Xero. How your software handles rounding may differ so it’s important to compare the values returned in Xero’s API response to confirm totals match. We have a guide explaining how Xero handles rounding.
If your product handles tax in any way then it will be important to map your tax rates to those in Xero. This is to ensure the correct tax rate is used on invoices, expenses etc.
It’s important to note that there are regional versions of Xero which support automatic filing of tax returns. For those Xero features to work properly you will need to use the tax rates within Xero; or give the user the option to create them if necessary. For other versions of Xero, mapping tax rates in your system to tax rates in Xero will help utilise any setup they have already done. We request that you avoid posting the specific tax amounts unless you’ve discussed it with your developer evangelist first.
You should use the same approach as per the account mapping in Checkpoint 13 above, we have more details in the taxes section of our Integration Best Practices Guide. You may also wantt to look at our tax guide to get a better understanding.
When applying payments to invoices or creating spend/receive money transactions, an account to which this monetary transaction is coded to must also be mapped. You should use the same approach as per the Account Mapping above. Note that you should present only accounts that can be used to apply payments, which will be those that contain one of the following elements in a response from the accounts endpoint.
Deep linking makes for a seamless user experience between your product and Xero. You can link to most resources in Xero e.g. an invoice, an item, a contact, a bank account. It provides a quick and easy way for the user to jump into Xero to see or take action against the resource referenced in your product. Follow our guide to ensure deep linking is implemented correctly, this is important as it ensures the correct organisation is opened for users with multiple organisations.
If your product creates invoices in Xero it might be useful to provide a default option for the status that should be used. Invoices can be created as Draft, Submitted for Approval or Approved. Having a dropdown of these statuses in your setup screen/view allows the user to select their preference for when your integration creates invoices and ensures your integration is working with Xero in the way the user does.
If your product creates invoices or bank transactions in Xero it might be useful to set the field to a url of the related item in your product. There will be a link added in Xero saying ‘Go to [yourAppName]’, this provides a seamless way for the user to jump straight into your product to see the related object etc.
We have consistently found that customers like to see the transparency of what apps are syncing into Xero. It can also be beneficial for auditing purposes. A great way to provide this functionality is to provide a log of the calls you’ve made to Xero. Usually this is a list of the POST or PUT calls. This is so customers can see objects that have been sent to Xero. It’s great to extend this functionality to show the customer a deep link to the object in Xero or your own app. It’s also the perfect way to show customers if there was an issue with syncing to Xero, that way they can see what the error was and can decide how they can resolve this.
