Xero API Limits
API Usage Limits
There is a daily limit of 1000 API calls that a provider can make against a particular Xero organisation in a rolling 24 hour period for each organisation connected to. If you exceed this rate limit you will receive a HTTP 503 (Service Unavailable) response with the message
oauth_problem=rate%20limit%20exceeded in the http response body.
Requests per minute
In addition to the daily limit, each OAuth access token can be used up to 60 times in any 60 second period. This rate limit is based on a rolling 60 second window, if the access token has been used more than 60 times in the past 60 seconds you will have exceeded the rate limit. If this rate limit is exceeded, the API will return HTTP 503 (Service Unavailable) with the message
oauth_problem=rate limit exceeded in the http response body. It is advisable to make no more than one request per second to avoid this.
Request Size Limit
A single POST to the Accounting or Payroll APIs has a size limit of 3.5MB. There is no limit to the number of elements within a request, provided the overall request size does not exceed 3.5MB. A single POST to the Files API has a size limit of 10MB.
Note: When posting form-encoded xml to the API, the encoded data will be approx 50% larger than the original xml message.
However, to ensure you receive a timely response from the API (large inserts can take quite a while), we recommend you look to batch elements in bundles of up to 50.
Encountering a rate limit
If you encounter a limit, do not continue to make requests as this may continue to add to your limitation. The most common issue encountered is the 60 requests/min rate limit. If possible, queue requests and allow a few seconds before attempting to make another request.
Private application limits
You can create a maximum of 2 private applications against a Xero organisation regardless of the user that created the application.
General Xero usage
Xero is not suitable for all types of business, particularly those with very high transaction volumes. Please see our notes on system limits.
Rate Limit FAQ
What if I need more than 1,000 calls a day?
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 is the best way to handle requests 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.
What if I need to retrieve large amounts of data from Xero?
One function which can cause an application to exceed the usage limits is extracting data from Xero eg:
– Retrieving all invoices does not return line item details for individual invoices. You can use pagination to retrieve line item details for 100 invoices at a time. Endpoints that currently support pagination are invoices and contacts. Our API roadmap includes bringing pagination to additional endpoints.
– When working with other endpoints, a request for each individual object may be required to get full details.
– An organisation can have many thousand Journals, which can be retrieved only in batches of 100.
In these situations, it may take some time to extract the required data – it is recommended that an application is structured to schedule or queue this function so there is no user expectation of an immediate response.
Does my application only have 1,000 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 1,000 API calls available in a given 24 hour period.
What if my application still cannot function correctly within the Xero API limits?
While the current API limits are not flexible, we can assist API users with advice on making their calls more efficient. Please contact us and we can advise.
Xero is designed for volumes of up to 1,000 Sales invoices (Accounts Receivables) and 1,000 Purchases bills (Accounts Payables) per month, dependent also on the frequency of invoicing during the month, variability of amounts and the frequency of sales tax reporting requirements.
Bank Transactions – Spend & Receive Money
Xero is designed for volumes of up to around 2,000 bank transactions per month, also dependent on the frequency of transactions during the month and variability of transaction values.
Xero recommends a maximum number of 4,000 tacked inventory items per organisation. Performance issues may occur when the total number of tracked items in an organisation exceeds this limit. We recommend you only create or update 100 items per API request.
Contact lists of greater than 10,000 could cause performance issues.
Xero will work with higher levels than this but the performance of some features and reports may become degraded.
Xero Pricing Plan Limits
Starter or small plan
Xero organisations using the “Small” pricing plan can enter up to 5 approved Accounts Receivable invoices and 5 approved Accounts Payable invoices per month. The invoice date (not the creation date) is used to determine which month an invoice was entered.
If you exceed this invoice limit when using the Xero API you will receive a HTTP 400 response code with the following error message:
<validationerror> <message>You have reached the limit of invoices you can approve. </message> </validationerror>
Partner edition plans
Xero partner edition plans such as cashbook and ledger organisations, can be connected to the Xero API.
Authorisation of connections to cashbook or ledger organisations must be done by a member of the practice staff – managed client or cashbook client roles cannot authorise an API connection.
Note that as these plans do not include invoicing functionality, any invoices created via the API could not be edited or modified, so this function is recommended to be avoided.