Xero Developer

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.

What app type should I use?

Xero has three types of API applications: Private, Public and Partner. The different app types have different authentication methods and are designed to suit different use cases. Check out our API Application Types guide for all the details.

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

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.

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.

How do I get support for building my integration?

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.

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.

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 a HTTP 503 (Service Unavailable) response. For a full list of API limits, pleace check our API Limits page

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.

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

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

It is recommended that applications queue requests to the Xero API. This will allow you to ensure requests are within the supported limits, and will also allow your application to function even in the event that it cannot reach the Xero API temporarily.

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

Applications that connect to more than one Xero organisation (Public and Partner) have a per organisation usage limit. 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.

Are there any recommended usage limits for Xero?

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

What Authentication do you support?

We only support OAuth 1.0a. This means we don't support API keys or basic password authentication

Can you give me an API key?

The Xero API does not support basic API Key authentication. Our API uses OAuth1.0a which means you need to register your app to get a consumer key and consumer secret which you use to access the API. Depending on the type of app you register you may also need to upload a X509 Public Key Certificate.

Whats with OAuth1a? Any plans for OAuth2?

OAuth1.0a has served us well but we appreciate that it's less convenient than OAuth2.0. We will look to transition to OAuth2.0 in the future but no specific details to share at the moment.

How do I redirect back to my app once a Xero user has authorised my app?

In order to redirect a user back to your app, you'll need to specify a callback URL parameter. The base of the URL will need to match the callback domain you set when registering the app. You can find more details on our OAuth Callback Domains page.

I'm getting an OAuth error. How do I fix it?

We have a list of the most common OAuth errors and potential fixes on our OAuth Issues page.

How does OAuth differ between app types?

A Private app uses RSA-SHA1 for signing and two-legged OAuth 1.0a. This generates a token that never expires.

Public apps use HMAC-SHA1 for signing and three-legged OAuth 1.0a. The generated token expires after 30 minutes and then the user must re-authenticate to get a new access token.

Partner apps use RSA-SHA1 for signing and three-legged OAuth 1.0a. The generated token expires after 30 minute like Public apps, but with Partner apps the developer can renew the token when it expires without the user reauthenticating.

What is three-legged auth?

This is where the end user is redirected to Xero to login and granted an access token to the app. The OAuth Bible has a great explanation.

What is two-legged auth?

During the creation of a Private App, the developer will select a single Xero org to connect to and generates a token. This token is used to sign requests and never expires, so no access token renewal is needed. It's commonly known as two-legged but is actually one legged, when you register the app. The OAuth Bible has a great explanation.

Is it possible for my app to have multiple active connections to a single Xero Organisation?

Yes. If multiple Xero users from the same organisation have authorised a connection to your app you could have multiple active connections. Your app will need to be able to keep track of the each connection's token in order for this to work.

There's no real benefit to managing multiple connections though, it just makes your token management more complicated. It won't give you additional rate limits.

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

Can I restrict the permissions given to an app?

Currently it's not possible to grant a subset of permissions to App using the API. Apps have the same permissions that a Standard user would.

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.

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 tha API.

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.

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.

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.

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.

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.

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 a 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.

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.

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.

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

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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.

Frequently asked questions