To become certified, your integration with Xero needs to meet our minimum requirements. Additional requirements may apply depending on the functionality of your app.
Outlined below are the checkpoints we will review your integration against during the certification process. Take time to review these before you submit your integration for certification.
If you need help, check out our developer forums and our developer youtube channel. If you need further help, get in contact with us via the developer support form or reach out to your developer evangelist.
The application name must reflect the go-to-market name of your app or product and cannot 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:
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 our 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 the limits.
Only 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 integration continues to meet requirements.
We’re asking all apps to build a Sign up with Xero flow to enable 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. As part of your implementation we encourage you to consider leveraging Sign In with Xero too, see checkpoint 17. Doing so will create a seamless sign in and sign up experience.
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 need your attention, rather than having to work through a large amount of historical 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. 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 and 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, you will need mapping functionality so that users can 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.
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 ensure the correct tax rate is used on invoices, quotes etc. There are regional versions of Xero which support automatic filing of tax returns; implementing tax correctly is crucial to those features working properly.
If your integration does not handle tax then you may wish to rely on Xero's tax defaults. If you don't supply a TaxType Xero will use the default tax rate on the Chart of Accounts account that the line item is coded to. Note that default tax rates for Contacts or Items are not applied in the same way.
If your integration does handle tax then you will need to use the tax rates within Xero. Similar to account mapping in checkpoint 13 above, you should allow customers to map Xero tax rates to your tax rates; or give the user the option to create them if necessary. We request that you avoid posting the specific tax amounts unless you’ve discussed it with your developer evangelist first.
More details can be found in the taxes section of our Integration Best Practices Guide, and we also have a guide to better understanding tax in Xero.
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.
We’re asking all apps to consider implementing Sign in with Xero which allows 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.
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.
