Frequently asked questions

Get help with common queries


API Updates*

Can you add this feature I want to the API?*

If you want to show your support for a feature not currently in the API then please add your votes and comments to our UserVoice page.

How do you decide which features get on the roadmap?*

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.

When is feature X going to be supported/available?*

In the Xero Developer team we try and be as transparent as possible letting developers know what we're up to using our public roadmap.

Will you make changes to your API that will leave my integration unusable?*

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.

Getting Started*

Can you give me an API key?*

The Xero API does not support basic API Key authentication. Our API uses OAuth 2.0 which means you need to register your app to get a client id and client secret which you use to access the API.

How can I try out the API?*

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.

How do I connect Xero to my Salesforce/SQL Database/thing you have no SDK for?*

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

How do I get a Xero account to develop/test against?*

The first step is to sign up for a free Xero account. Once you have done that, you have two options as to how you can begin development without incurring any cost:

  • Use the demo company (recommended)

  • Start a trial or paid Xero organisation subscription

Check out our Development Accounts guide for more details.

How do I get support for building my integration?*

Hopefully everything you need to know is on 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.

What Authentication do you support?*

We currently support OAuth 1.0a and OAuth 2.0. However, OAuth 1.0a is in the process of being deprecated and OAuth 2.0 is required for all new integrations.

What are some best practices for building an integration?*

For some of the basics check out our Integration Best Practices guide. After that, browse through the rest of our how-to guides to find more guidance specific to your integration.

What kind of App should I build?*

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 forumsdeveloper forums and UserVoice page to get you started with some ideas.


Xero is not suitable for all types of business, particularly those with very high transaction volumes. Please see our notes on system limits.

Can I get my rate limits increased?*

No, our rate limits are the same for all apps connecting to the API. If you are hitting rate limits there are a number of things you can do to make your integration more efficient.

Does my application only have 5000 requests for all my users?*

Rate limits apply to each connection. For example, if two separate Xero organisations are connected to an application, each connection would have 5000 API calls available in a given 24 hour period.

What are the Xero API rate limits?*

There are limits to the number of API calls that your application can make against a particular Xero organisation.

  • Minute Limit: 60 calls in a rolling 60 second window

  • Daily Limit: 5000 calls in a rolling 24 hour window

If you exceed either rate limit you will receive an HTTP 429 (too many requests) response. For a full list of API limits, pleae check our API Limits page

What if I need to do lots of creating and updating?*

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.

What if I need to retrieve large amounts of data from Xero?*

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 invoicescontactsbank 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

What is the best way to handle rate limits on my side?*

If you exceed a rate limit you will receive a Retry-After http header that tells you how many seconds to wait before making another request.

OAuth 1.0a Migration*

Can I/should I still get my OAuth 1.0a app certified?*

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

I use multiple private apps to integrate with with multiple Xero organisations and I don’t want to become app partner. What should I do in OAuth 2.0?*

If you have a custom integration with multiple organisations (e.g an accounting practice or franchise) then get in touch with us at, tell us more about your use case and we can adjust your connection limit accordingly.

Is it possible to get the authorization code displayed in the browser (i.e. not use a redirect url) like it was in OAuth1.0a?*

The redirect URL will return a code in the query string, but we will not display it in the browser. The use of a redirect URL is required in OAuth 2.0.

What is happening to public/partner/private apps?*

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.

Will current partners have to re-register? Will partner apps have to certify again?*

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.

Will the current OAuth 1.0a SDKs be updated to support OAuth 2.0?*

We have released 6 new SDKs (.NET, NodeJS, PHP, Java, Ruby, Python) all built from the ground up with OAuth 2.0.

OAuth 2.0*

Can I have more than three redirect URIs for my app?*

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.

Can I use a wildcard in my redirect URI?*

The OAuth 2.0 spec (section 3.1.2 of RFC 6749) requires that a redirection URI must be an absolute URI. The use of wildcards in redirect URI is not supported.

How should I handle callback failure?*

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.

Is there an equivalent of two-legged private apps in OAuth 2.0?*

No, all users will follow the same OAuth 2.0 code flow. Once you have an access token and refresh token you can refresh indefinitely or until the token is revoked by the user.

What do I do if a token refresh fails?*

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.

What is the expiration for a 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.

When is OAuth 1.0a being deprecated?*

Here's what to expect with the move to OAuth 2.0:

  • 2nd December 2019: Developers could no longer create new OAuth 1.0a apps

  • Mid-December 2019: A migration endpoint was released allowing partner apps to seamlessly migrate existing connections to OAuth 2.0

  • December 2020: All app partners and accounting and bookkeeping partners expected to be migrated.

  • March 2021: OAuth 1.0a will no longer be supported for any integrations

Where can I find a developer to help build or migrate my app?*

Find developers with proven experience building integrations with the Xero API on the Xero marketplace.

Will OAuth 2.0 support desktop/mobile/single-page apps that can’t keep a client secret confidential?*

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.

Partner Program*

Can I move down tiers?*

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.

How are tiers calculated?*

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.

How can I improve my app marketplace rating?*

Everything you need to know about marketplace ratings and reviews can be found in our guide, going live on 1 November.

How can I move up a tier?*

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.

How can I track my progress in between Xero’s updates?*

At this stage, Xero won’t be able to provide you with an update on your metrics in between our official updates in January, April, July and October.

How do I know which tier I’m in?*

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.

How do you define active connections?*

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.

How do you define the “Xerocon Sponsorship” requirement in the app partner program?*

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.

How do you measure annual connection growth?*

This is the percentage growth of your app’s number active connections, measured year-on-year, using a 12 month rolling average.

How often can I change tiers?*

Partners can apply for a new tier at any time, but we will only change tiers at set quarters, in line with the quarterly updates (in January, April, July and October).

What are the benefits of the Xero app partner program for me*

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.

What happens if I think the metrics in your update are wrong*

If you think we’ve made an error in calculating your partner requirement metrics, you can lodge a request with us here. Xero will review your request, but we do retain final say.

What kind of partner requirements are the tiers based on?*

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.

What’s required to meet the tracked referrals requirement in the app partner program?*

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.

Where does my marketplace rating come from?*

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.

Will there be more features coming in the partner program?*

As the program matures, we will continue to review the expectations of, and the benefits to, our app partners. As always we’ll give you plenty of notice before we change anything.

Will you make which tier I’m in public?*

There are no plans currently to share your tier publicly on our website. We will review this position once the program is more mature.


I need to build an integration but the owner doesn't want to allow me access to their data. What do I do?*

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.

What permissions does a user need to connect an App via the API?*

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.

What permissions does an app have when using the API?*

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.

Why is my organisation missing from the drop down when authorising an app?*

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.

Private App Deprecation*

How do I build a machine to machine integration?*

Check out our guide for building machine to machine integrations.

Why are you deprecating private apps?*

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.

Will you support long lived access tokens?*

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.

Will you support the client credentials grant type?*

No, but it is still possible to build machine to machine style integrations.

Xero Ecosystem Security Requirements Update*

How often do I need to do this?*

The security assessment will need to be undertaken annually.

How will I know if my app meets these standards?*

We’re still working through the details of the process, but we’ll contact you when you need to undertake the security assessment and let you know the outcome of that assessment.

Important information about new global Xero ecosystem security requirements*

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.

We’ll keep our app partners updated via, our twitter account and our developer emails.

What will the security assessments involve?*

  • An annual self assessment against the standard

  • These new requirements will include, but are not limited to, API risk rating, authentication, certification, personnel security, encryption and audit logging

  • 2SA will be the minimum level of account authentication but this will be provided already if your app connects with Sign in with Xero

Which apps will be affected?*

  • All app partners who wish to be certified and listed in the Xero app marketplace

  • New app partners need to comply from 1 January 2020

  • Existing app partners have until 30 June 2020 to comply

Xero Functionality*

Can the API be used on all Xero plans/SKUs?*

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.

Does the Xero API use defaults for things like tax rates, account codes etc?*

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.

How does this accounting thing work? (WHY am I getting an error that the tax rate can't be used with the account code?)*

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.