caret

Certification Checkpoints


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.


Required for all integrations

Checkpoint 1: App name

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.

Checkpoint 2: Branding

Checkpoint 3: Connection

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:

  • Display the name of the tenant that has been connected. You can get the tenant name from the connections endpoint. If it is an organisation tenant type you can also get it from the organisations endpoint.
  • Display the current status of the connection(s) with Xero. If disconnected, provide a button to connect to Xero.
  • Include a button to disconnect the integration, see the removing connections and revoking tokens section for more info.
  • Handle a disconnect from Xero’s side. Users can disconnect apps from the Connected Apps screen (Xero > org name > settings > connected apps > disconnect app). If you try to make a call to Xero when this has occurred, you will get an error back from the API. Users should be alerted and/or guided to reconnect and the status of the connection should be updated.
  • Consider whether you are catering for a 1:1 or multi-org connection. Think about how you might design this process. Do you need the user to confirm which org they would like to use? Can you use the eventId on a connection to make this experience better? Do I need to disconnect their unused orgs?
Don't:
  • Never request a user’s Xero login details within your application; you should always use OAuth for authentication.
  • Avoid the use of pop-up windows or new tabs in the authentication process if possible. Redirecting users to Xero in a pop-up window can disrupt the user journey or be blocked by a pop-up blocker.
  • Never show or store sensitive data like the access token, client id and client secret in the client side of the application (e.g. frontend of a web app or local configuration files for native apps).

Checkpoint 4: Error handling

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.

Checkpoint 5: Offline_access

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.

Checkpoint 6: Rate limit hit management

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.

Checkpoint 7: Scopes

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.

Checkpoint 8: Sign up with Xero - new requirement

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.


Required if getting data

Checkpoint 9: Modified after

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.

Checkpoint 10: paging

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.

Checkpoint 11: Webhooks

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.


Required if posting or putting data

Checkpoint 12: Account mapping

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.

Checkpoint 13: Currency

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.

Checkpoint 14: Rounding

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.

Checkpoint 15: Taxes

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.


Required if posting payments

Checkpoint 16: Payment account mapping

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.

  • <Type>BANK</Type> (A bank type account)
  • <EnablePaymentsToAccount>true</EnablePaymentsToAccount> (an account that has the ‘enable payments to this account’ option enabled)


Preferred user experience

Checkpoint 17: Sign in with Xero

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.

Checkpoint 18: Deep linking

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.

Checkpoint 19: Invoice status

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.

Checkpoint 20: Invoice URL and bank transactions URL

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.

Checkpoint 21: Logs

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.