The roadmap is driven by a number of factors such as developer feedback, User Voice feature requests and Xero's internal product goals. Priorities and circumstances are constantly changing so please use the roadmap as an insight into our current plans rather than a binding commitment.
Whenever we make a change to the API we try to do so in an additive way that won't break existing integrations. However, occasionally things can change in a way that isn't backwards compatible. Make sure that you stay in touch so we can let you know when things do.
The quickest way to try out the API is to set up your demo company and dive into the API Previewer. Most of the API functionality is supported and you can quickly start playing with real calls against demo data.
We've got SDKs to cover the most used technologies in the community but we'll never cater for everyone. If we don't support your particular tech then your best bet is to look for help on our developer forums. You can also use our OpenAPI spec to generate your own SDK
Hopefully everything you need to know is on developer.xero.com but if you're still stuck then you can reach out to other developers on community or stack overflow. If you're really stuck you can even hire Xero certified developer to help you out.
That's really up to you! Get connected with accountants and business owners to find out how you can help them be successful. There are plenty of resources like our business forums, developer forums and UserVoice page to get you started with some ideas.
Quite often, applications that you might believe would exceed the Xero API rate limits, can in fact work within the limits by analysing the structure of how you intend to use the Xero API
You can do more than one thing in a single request: For example, you can create more than one Invoice in a single PUT or POST Invoices API call. While there is no upper limit in the number of nodes that can be sent at one time, a ceiling of about 50 nodes per request is practical - this will ensure a request does not exceed the maximum size of 3.5MB. You should also review our notes on summarizing validation errors.
If you are hitting rate limits because you retrieve a large amount of data from Xero there are a couple of features you should be taking advantage of:
You can use pagination to retrieve line item details for 100 items (e.g. Invoices) at a time. Endpoints on the Accounting API that currently support pagination are invoices, contacts, bank transactions and manual journals. All major endpoints on the Payroll, Files and Assets APIs also support paging.
Use the If-Modified-Since header to retrieve only what's changed since your previous request
We encourage anyone building new apps to use OAuth 2.0 but we will continue to certify OAuth 1.0a integrations until the end of March 2020. Please be aware that if you choose to launch with OAuth 1.0a you will be required to migrate it to OAuth 2.0 before December 2020
If you have a custom integration with multiple organisations (e.g an accounting practice or franchise) then get in touch with us at email@example.com, tell us more about your use case and we can adjust your connection limit accordingly.
The concept of "app types" will be going away with OAuth 2.0. All apps will use the same authentication flow. Connection limits limits will be the main difference between certified (i.e. partner) and uncertified (i.e. public/private) apps. New apps will be able to connect with up to 25 organisations before they need to get certified to have the connection limit removed. Please see the OAuth 2.0 docs for more details.
All OAuth 2.0 apps will be able to maintain an offline connection (like partner apps can currently).
We have a migration endpoint that allows partner apps to swap existing OAuth 1.0a tokens for new OAuth 2.0 tokens. Users won't have to reauthorize your app.
We won’t be offering a migration flow for public or private apps. If you have clients using those apps then you will need to create a new OAuth 2.0 app and ask them to re-authorise.
There’s no need for re-certification. Partners are able to generate an OAuth 2.0 client id and secret for their existing partner app, which will give them no connection limit, as well as any special scopes they currently have.
If your scenario requires more than three redirect URIs (e.g. users need to be redirected back to a number of different subdomains) then you can create a central redirect URI and use the state parameter to pass the values your app needs to produce the desired user experience.
Create a central redirect UI for your app to complete the authorization step.
Send application specific parameters (e.g. the subdomain) in the state parameter. Take care to also still guard against CSRF.
When the user is redirected back to your central redirect URI the state parameter is sent back to your app.
Your app can then use the value in the state parameter to determine which URL to send the user to. Make sure you validate for CSRF protection.
Note: This approach could be compromised by the open redirector threat described in RFC 6819. Be careful to protect these parameters by encrypting the state or verifying them by some other means.
If the callback fails for any reason you will need to send the user through the auth flow again. If the user got as far as connecting their org the first time, it will show as already connected the second time. They can continue to click through as normal to be redirected back to your app with a new code.
If you don't receive a response from a token refresh you can retry using your existing refresh token for up to 30 minutes. If you can’t refresh your access token in that time you’ll need to send the user through the authorization flow again to get a code that can be exchanged for a new access and refresh token.
Unused refresh tokens expire after 60 days. If you don’t refresh your access token within 60 days the user will need to reauthorise your app.
When you perform a token refresh, you should replace your existing refresh token with the new one returned in the response. If, for whatever reason, you don't receive the response you can retry refreshing your existing refresh token for a grace period of 30 minutes.
Xero supports the Proof Key for Code Exchange (PKCE) extension to the authorization code flow. This allows native apps to securely connect to our API without needing to store a client secret. Single page apps are not currently supported.
We want you to succeed, so we have built in a six-month grace period. If you fail to maintain the necessary criteria for your existing tier, we’ll give you six months to meet all of the necessary requirements again. If in that time you don’t meet those requirements, you will be moved into the appropriate new tier.
To join the app partner program, you must have successfully completed Xero’s app partner certification and maintain at least five (5) customers on your solution who are actively using Xero. Once you meet the minimum threshold, you can move through the tiers by attaining various partner requirements. View the requirements here.
Once you meet the requirements of a new tier, you need to apply to move into the next tier by filling in this form. We will let you know if you are successful, or if there are any areas you need to work on before you can move into a new tier.
Xero will send you an update each quarter (in January, April, July and October). It will include key metrics, letting you know how you’re tracking against partner tiering requirements and which tier you are in.
Active connections is defined as paying Xero subscribers, connected to your integrated product, as measured by an active API session to your registered partner key at least once within a calendar month.
To meet this requirement you must sponsor at least one Xerocon event within the current Xerocon season, which begins in September of each year. The current season began in September 2017 with Xerocon Melbourne and will end with Xerocon Atlanta in June 2018. The next Xerocon season begins with Xerocon Brisbane in September 2018.
Xero brings together over 40,000 developers, 100,000 plus advisors and more than two million subscribers in our unique ecosystem of cloud software solutions for small businesses. Certifying your app with Xero and joining our partner program gives you access to our thriving ecosystem community through the Xero app marketplace and access to Xero resources and support at every step of your journey. Best of all, joining us is free. Find more information on the benefits of our program here.
App partners can achieve one of four tiers based on number and growth of active connections (customers actively using your Xero integration), app review ratings, and participation in the Xero community. More information about the requirements for each tier can be found here.
To meet this requirement at least 20% of your app’s new net connections (that’s how many new active connections you have with Xero within the last year) need to be tracked referrals to Xero, using an XTID code.
Xero subscribers leave reviews for their Xero integrated apps on our community site. Your rating average and the number of times you’ve been reviewed is then pulled through onto your marketplace tile. This is also one of the requirements in the Xero app partner program and this data is refreshed once a month.
Integrations should be fully built and tested before being connected to a live organisation. Once the integration is complete, you can hand it over to a Standard or Adviser level user to connect. Please see our Development Account page for ways to test your integration without cost.
The API essentially works on behalf of the user that authorised it to connect. Since the API acts with Standard user permissions, the user that connects the integration has to have at least Standard user permissions.
Generally apps using the API have the permissions of a Standard level user. To access reporting APIs the authorising user must have Reports access and for Payroll APIs the authorising user must be a payroll admin.
If your organisation isn't showing in the organisation dropdown, this means either that you don't have Standard or Adviser level permissions in that organisation, or you already connected that particular app to the organisation.
For OAuth 2.0 we’ve deliberately chosen to only support the code grant type because it is the most suitable grant type for our API access model. All our APIs require an app to act on behalf of a user so it is appropriate that users (resource owners) explicitly grant consent to those apps as part of an authorization flow.
No, we've chosen to implement short-lived tokens with long-lived authorizations. This will beneficial for our performance at scale.
Additionally, there is more risk associated with long-lived tokens in OAuth 2.0 because they are the only authorisation required to call the API. OAuth 1.0a also required a private key to generate the signature which was checked on every request.
At Xero, we take the responsibility of managing our community’s data privacy and security seriously. As part of the work Xero has been doing with the Australian Tax Office and other industry players, we have developed a set of agreed security standards to be applied globally to our ecosystem. These come into effect for new app partners certified after 1 January 2020 and existing app partners have until 30 June 2020 to comply. We’re still working through all the details of our new process, but wanted to share this information with you early, so you can start to understand what these changes mean for your app.
In preparation to meet these new requirements, Xero will be updating our security requirements for our app and developer partners, as well as Xero’s App and Developer Partner Terms of Agreement.
All app partners will need to undertake a security assessment which will be reviewed by Xero’s security team. App partners who reach 1000 or more connections will be required to undertake an advanced security assessment which will also be reviewed by Xero’s security team. App partners will not be certified or listed in Xero’s app marketplace without passing these assessments. App partners will need to undertake and pass the security assessment on an annual basis.
The API can be used with all Xero plans, but not all features will necessarily be available. Payroll API requires a Payroll plan. Cashbook and Ledger plans exclude certain features (e.g. invoicing) but can still be connected to via the API.
The Xero API uses very few of the defaults that can be set through the Xero UI. The only defaults it will use are the tax rate from the account code if the tax rate isn't sent, and the description, account code and price on inventory items (but not tax rate). All other information must be specified in your call.
It's best to become familiar with the Xero platform and basic accounting principles before designing an integration. Xero accounts are free, and each comes with a fully functional Demo Company. The Demo company is populated with sample data to give you an idea of what items should look like. We also have an extensive Help Centre with information on each feature as well as how-to guides specific to the API. You may also want to consult with a Xero Certified Adviser who can instruct you on the accounting requirements many clients may have.