Certification Checkpoints
What's this all about?
As part of becoming a certified App Partner we will review your integration to make sure it’s the best it can be for Xero users. Each integration is different and therefore there is no full list of the things you’ll need to cater for, however there are a lot of common criteria we look for. This self service checklist will best prepare you for your final review with us by helping you work through all the common issues we usually find. Once you’ve ticked off each of the checkpoints below you’ll be ready for your review and you’ll have saved yourself and us heaps of time by getting the basics sorted up front. Simply work your way through each checkpoint, note that some are mandatory, but some may not be relevant due to the way your integration works.
What if I’m stuck?
If you’re stuck, we’ll help! We’ll have been in touch over email by this point, so just drop us a reply to tell us you need help, or email api@xero.com. Let us know the checkpoint number you need help with and give us the details of the problem you’re facing.
Checkpoint 1: Application Email Address
Mandatory - As this is the email address associated with your app, it is important this is active and not a personal email address of the developer. We generally recommend this is set to a generic email address (eg: developers@companyname.com) so you will continue to receive important notifications from us, even if a staff member leaves. If you’ve already created an app under your personal email that’s fine and you can continue to use that app for your own use, but for production environments it’s best to get an app registered that is under a shared email address:
- Go to https://www.xero.com/signup/ and create a Xero login with a shared email address
- Check the email box for our account verification email, then click the link in the email to verify email ownership and to create a password for the account. You'll be prompted to create a Xero organisation but you don't need to do this.
- Click My Apps to add your app
Checkpoint 2: Application Name
Mandatory - To avoid confusion, the application name cannot contain the word Xero, and must reflect the name of your website or product. The name can be viewed/updated by going to the
My Apps.
Checkpoint 3: User Agent
Mandatory - The user agent string must be set in your app and must contain your consumer token (you can find this in the MyApps section of the dev portal
https://developer.xero.com/myapps/ ). This allows our support systems to easily and quickly identify the source of any problem API calls. 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 individual API call log.
Checkpoint 4: Connection
Mandatory - An application should never request a user’s Xero login details within their application - the OAuth authentication system should always be used to connect to their Xero data. At this stage you should be using the
Public app type and we’ll upgrade you to the
Partner app type following this review.
There should be a setup screen/view that allows the user to connect to Xero and administer the connection. You should ensure you implement the following:
Checkpoint 4a: Display the current connection status is. If disconnected provide a button to connect to Xero.
Checkpoint 4b: Display the name of the organisation in Xero that has been connected, you can get this from the Organisation endpoint.
Checkpoint 4c: An option to disconnect. Note that you can’t programmatically disconnect from Xero, instead simply purge any record of the oauth tokens on your side.
Checkpoint 4d: No pop-ups. Make sure the user is not redirected to Xero in a pop-up window, this can disrupt the user journey or be blocked by a pop-up blocker.
Since your application will have long term access to an organisation, an end user may want to revoke access at any time. This can be done inside Xero via the Add-ons settings screen (Settings > General Settings > Connected Apps). If revoked you need to follow the standard initial connection process by reflecting the disconnected state and providing a button in the setup screen/view in your product. You may also want to notify the user in some way they are no longer connected, for example an in app notification or an email. This is because there are circumstances where the disconnection is unintentional and the user must reconnect to keep the integration working. You can use the revoke access option in Xero mentioned above to easily test this.
Checkpoint 5: Account Mapping
Mandatory if posting transactions - 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.
Checkpoint 6: Payment Account Mapping
Mandatory if posting payments - When applying payments to invoices or creating spend/receive money transactions, an account to which this monetary transaction is coded to must also to be mapped. You should use the same approach as per the Account Mapping in Checkpoint 5 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)
Checkpoint 7: Taxes
Mandatory if posting transactions - 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 currently the AU, NZ and UK regional versions of Xero support automatic filing of tax returns, and therefore the default tax rates must be used. For other versions of Xero, mapping Tax Rates in your system to Tax Rates in Xero may involve prompting the user to map or create new tax rates in Xero via the API.
You should use the same approach as per the Account Mapping in Checkpoint 5 above and we have more details in the Taxes section of our
Integration Best Practices Guide, and we have a guide to better understanding tax in Xero
here.
Checkpoint 8: Currency
Mandatory if posting transactions - 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, it’s not possible to create them via the API. Therefore, you must handle situations where your product is using a currency that is not registered in Xero, you will receive an API error message if you attempt to use a currency that is not.
You can read a list of the registered currencies from the
Currencies endpoint and notify the user if any are missing. If they are you could provide a link straight to the currency settings area in Xero and instruct the user to register the missing currency. If you link to Xero ensure you use
deep linking.
Checkpoint 9: Deep Linking
Not mandatory - If your product creates items in Xero such as invoices it might be useful to provide buttons/links to these from the related item in your product. This provides a quick and easy way for the user to jump into Xero to see the related item or take an against against it. Deep linking must be used in this case, deep linking will ensure that if the user has access to more than one Xero organisation the correct one is opened, i.e. the one where the item was created. We have a guide to deep linking
here.
Checkpoint 10: Rounding
Not mandatory - 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 11: Invoice Status
Not mandatory - 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 12: Invoice Url
Not mandatory - If your product creates invoices in Xero it might be useful to set the
field to a url of the related item in your product. When set a button is added to the top of the invoice in Xero saying ‘Go to [yourAppName]’, this provides a seamless way for the user to jump straight into your product to see the related invoice/job/customer etc.
Checkpoint 13: Error Handling
Not mandatory - 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.
Checkpoint 14: Paging and Modified After
Not mandatory - 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.
In addition, the Modified After parameter is useful to introduce efficiencies by getting only records created or modified since the timestamp you specify. Using this you can ensure you’re only getting back records that you need your attention rather than having to work through loads of historic records.
