Release Notes
To be notified as we release new features, subscribe to the Xero Developer mailing list.
Date: May 2, 2013
Version 2.24.4084
Bug fixes
1. JSON response for GET Invoices were returning the LineAmountType value as an integer rather than a string. Such that the integers [0,1,2] are being returned in place of [NoTax, Inclusive, Exclusive]
2. Payments were being accepted for accounts that didn’t have “payments enabled”
3. GET CreditNotes – credit note not found are now returning a HTTP 404 rather than a HTTP 400 exception
Date: Apr 23, 2013
Version 2.24
Bug fixes
1. GET Organisation returning address details – issue not returning addresses is resolved
2. GET CreditNotes – credit notes not found were returning HTTP 500′s in error
3. API Previewer – offset parameter issue for journals is resolved
What’s next?
1. Payroll API
Date: Mar 25, 2013
Version 2.23
New features and improvements
1. Apply credit notes to invoices
You can now allocate part or full amounts of credit notes to outstanding invoices. See Credit Notes
2. More details on GET CreditNotes
When retrieving credit notes you can now see details of all allocations to invoices. See Credit Notes
3. Support for Australian Tax Rate changes. Learn more
What’s next?
1. Payroll API
Date: Mar 11, 2013
Version 2.22
New features and improvements
1. Get Organisation improvements
- a shortcode for identifying an organisation is now shown
- address details for an organisation is now shown
See Organisation for more details
What’s next?
1. Credit note improvements
2. Payroll API
Date: Dec 10, 2012
Version 2.20
New features and improvements
1. 1099 report for US Users
What’s next?
1. Credit note improvements
Date: Oct 30, 2012
Version 2.19
New features and improvements
1. The Profit and Loss report now allows you to filter by a tracking category
2. The Balance Sheet report now allows you to filter by tracking category options
Other changes and bug fixes
OAuth signatures now support both the OAuth 1.0a and 1.0 final spec (1.0 final spec has a change for PUT requests)
Filenames are now correctly showing when attachments on invoices and receipts have spaces
What’s next?
1. 1099 Report for US users
Date: Oct 11, 2012
Version 2.174
New features and improvements
1. Mark invoices as been sent to a contact
If you send invoices via another system you can now reflect this by marking approved invoices as sent using the “SentToContact” element
See Invoices for more details
Other changes
2. Private API Application creation limits
We have decided to implement a limit to the number of private API applications that can be connected to a Xero organisation. This limit is 2 applications per Xero organisation.
This has been put in place to ensure the stability of the Xero API – in some limited circumstances, we have noticed developers creating multiple API application instances to bypass our rate limits, particularly in cases where they are making inefficient use of the API and do not wish to change their practices.
Note that we have placed this limit on a per organisation basis – a developer with access to 4 different Xero organisations could create 8 applications – 2 for each organisation (provided nobody else has created private API applications already tied to these organisations).
What’s next?
1. Reports by tracking category
Date: Sept 19, 2012
Version 2.17
New features and improvements
1. XML File Import for Conversions
A developer preview of a conversion file import tool is now available. This can be used to populate a chart of accounts, organisation settings and mark the setup guide as completed.
Learn more about conversion tools and services
What’s next?
1. Mark invoices as been sent to a contact
2. Retrieving ExpectedPaymentDate on Accounts Receivable invoices
Date : July 16, 2012
Version 2.16
New features and improvements
1. Attachments for Accounts Payables
In the same way that you can add attachments for receipts, you can now do this for Accounts Payable invoices. All the usual file formats (jpg,png,gif and pdf) are supported
See Attachments for more details
Bug Fixes
1. Fix for not being able to void approved invoices that contain description only lines or a zero invoice total
What’s next ?
Date : May 14, 2012
Version 2.15.39
Bug Fixes
- Rounding issue on Manual Journals – A rounding calculation on manual journals validation was preventing the entry of Manual Journals in certain circumstances.
- GET Journals: Offset not returning all journals with identical timestamps – A condition existed within the current GET Journals function where one or more Journals may not be returned if the CreatedDateUTC is identical to another Journal within that Xero organisation.
- PUT / POST Invoices: Comment only lines – on POST Invoices, comment line items consisting ofelement only were throwing validation errors for invoices with LineAmountTypes = Inclusive OR NoTax & status is above DRAFT (SUBMITTED, AUTHORISED).
What features are next ?
- Support for attachments on Accounts Payable invoices
- Mark invoices as been sent to a contact
Date : April 17, 2012
Version 2.15
New features and improvements
1.Manual Journals
You can now enter “POSTED” Manual Journals in addition to ‘DRAFT’ ManualJournals. There is also a new element to specify whether a manual journal should be shown on cash basis reports. We’ve also added support for URL links on manual journals via the Xero API so you can add a convenient link back to the relevant source data in your system – just like you can with invoices. Note that the code to display URLs within the main Xero application is yet to be deployed, so these links will only be visible after our next main application release.
See Manual Journals for more details.
2. Status Codes
If you exceed the Xero API rate limits the HTTP Status code returned is now a 503. This change was omitted in our previous release notes.
See Rate Limits for more details.
Bug Fixes
1. Support for description only line items on invoices with any supported LineAmountType (i.e. Exclusive,Inclusive,NoTax). Previously this was not working for Inclusive invoices
What’s next ?
- Support for attachments on Accounts Payable invoices
- Mark invoices as been sent to a contact
Date : 20 February, 2012
Version 2.14
New features and improvements
1.Where filters
Response times have improved when you use the ‘where’ parameter in your API calls to retrieve invoices and contacts. See our examples of the most common scenarios for applying these filters.
2. Discounts
You may have seen that the main Xero application released line item discount functionality today. In order to ensure discounts applied to invoices created in Xero are correctly displayed via the API, we have released some changes to support discounts on GET Invoices only. We will be adding support for add discounts to invoice lines via the API (PUT, POST Invoices) in the not too distant future.
3. Account codes for receipts
A new element “ShowInExpenseClaims” has been added to the response for GET Accounts. This lets you see which account codes are available for use with expense claim receipts. The value for this element is a boolean e.g.true
Bug Fixes
1. Fix for ‘order’ clause which was not always worked as expected.
2. All invoice data for Demo companies is now returned – some invoices were missing with non NZ demo companies.
3. Fix for retrieving journals when organisation has more than 32,000 journals
What’s next on the roadmap?
- Approved manual journals
- Application permissions
- Full support for discounts
Date : 19 December, 2011
Version 2.13
New features and improvements
1. Get list of users
The Users endpoint lets you get a list of the users for an organisation.
2. Enter receipts
You can now enter draft receipts for a user. You can also attach images to the receipts. See Receipts for more details.
3. Enter expense claims
Once you’ve entered some receipts you can now also submit these as part of an Expense claim for a user.
4. Australian Business Activity Statement Report
You can now retrieve published BAS Reports for Australian organisations via the Reports endpoint.
What’s next on the roadmap?
- Performance Improvements
- Approved Journals
Date : 24 November, 2011
Version 2.12.127 Hotfix
Bugfix: P&L Report
Since the main application release on 23/11/2011, the P&L report endpoint was returning a 500 error response for some Xero organisations.
Bugfix: Budget Summary Report
The budget summary report was not responding to provided querystring parameters and was displaying the default budget summary timeframe.
What’s next on the roadmap?
- Expense Claims
- Performance improvements & AP invoice file attachments
- Approved manual journals
Date : 08 November, 2011
Version 2.12
New Reports Endpoint
We have released a new report endpoint which is currently in closed private beta for Australian organisations.
This will be documented in a future release.
Bugfix: Invoice LineAmountTypes of NoTax
When specifying a LineAmountTypes of No tax, the line items were returning an incorrect TaxType of the default tax type for that account, though at 0% rate.
There was no net effect to this issue, other than a minor effect to the layout of PDF invoices generated with this condition.
A validation warning is now raised for inconsistencies between document TaxType and LineAmountType.
Date : 2 August, 2011
Version 2.11
New features and improvements
1. Enter bank transactions
You can now enter Spend Money and Receive Money transactions. You need to meet all the validation requirements for
this type of transaction. As per the Xero app there is no draft or submitted status for bank transactions. See Bank Transactions for more details.
2. GET Accounts now includes a Class element which is helpful when fetching a subset of accounts to show in your application. e.g. ASSET, EXPENSES
What’s next on the roadmap?
1. Expense Claims
Previous Releases
Date : 14 June, 2011
Version 2.09
New features and improvements
1. Approved Invoices & Credit Notes
You can now enter approved invoices and credit notes using the “AUTHORISED” status. Once an invoice has the AUTHORISED status you can apply payments to it in a subsequent API call.
You can now change the status of DRAFT or SUBMITTED invoices to be approved using the “AUTHORISED” status. Many users may still want to have invoices entered in Xero as drafts so consider giving your customers a choice of how their invoices get entered into Xero. Xero’s validation requirements for entering approved invoices and credit notes is stricter than that for entering drafts or submitted invoices. For example, you need to ensure that you include valid account codes for every line item.
We’ve now created a separate request on our Uservoice site for being able to trigger an email to send these invoices. We’ll closely monitor how much demand there is for this. If you are looking to enter many invoices in a single call then we recommend you make use of our enhanced error messaging for individual invoices by appending “summarizeErrors=false” to the end of your API calls. e.g. POST /api.xro/2.0/Invoices?summarizeErrors=false. See Invoices for more details.
2. Void & Delete Invoices and Credit Notes
You can now void approved invoices that have had no payments made against them and you can delete draft or submitted invoices. The status codes for these are “DELETED” and “VOIDED”. See Invoices for more details
3. You can now enter invoice lines with just a description e.g. no unit price or quantity will show on the invoice.
What’s next on the roadmap?
1. Bank Transactions (Spend and Receive Money)
2. Expense Claims
Date : 23 May, 2011
Version 2.08
New features and improvements
1. Employees
You can now create,update and retrieve basic employee details via the Xero API. Additionally you can now create hyperlinks to the details of employees stored in other systems.
2. Payments – support for non base currency.
You can now specify the exchange rate for payments applied to invoices in currencies other than your base currency. When you call GET Invoices for invoices raised in currencies other than your base currency a CurrencyRate element will now be included in the response. We’ve also added GET Payments as an alternate way to get invoice and credit note payments.
3. Organisation details
More details are now returned including end of financial year dates, lock dates, tax number, registration number and organisation creation date
4. Entering data in bulk
We’ve improved our validation of bulk API calls so entering many invoices in a single API call is now a lot easier e.g. if any invoices in the middle of a batch fail Xero’s validation then the correct responses are still returned for the successful invoices and you can see the validation error for each invoice that failed. All our endpoints have been upgraded with this improved validation. The new response messages for validating bulk API calls would mean a breaking change so to utilise this functionality you’ll need to append ?SummarizeErrors=false to the end of your API calls e.g. POST /api.xro/2.0/Invoices?SummarizeErrors=false.
5. Email sent
GET Invoices and GET CreditNotes now indicate when an invoice or credit note has been emailed to a customer.
6. Credit notes applied to invoices, reporting codes
These items were left out of our previous release notes. Any credit notes applied to an invoice are now returned in more detail when using GET Invoices. Reporting codes are returned on GET Accounts for New Zealand based organisations.
What’s next on the roadmap?
1. Approving invoices
This work is close to completion but needs some more polish and testing before release. We expect to release this in June 2011. At this stage the scope of this work is limited to allowing you to enter approved invoices and not trigger the sending of invoices via email. In this release we have improved how our invoice validation works and now have an option to get more detailed responses when entering many invoices in a single API call. This was a pre-requisite to the enabling of approved invoices. Stay tuned for more details on this.
Date : 23 March, 2011
Version 2.07
New features and improvements
1. Reporting APIs
Xero’s most commonly viewed reports (listed below) can now be retrieved using the Xero API.
Aged Payables By Contact
Aged Receivables By Contact
Balance Sheet
Bank Statement
Bank Summary
Budget Summary
Executive Summary
GST Report (New Zealand organisations only)
Profit and Loss
Trial Balance
Try the API Previewer to explore these reports or read our API Reference for more details.
2. Bug Fixes
- Partner applications now show correctly in Xero Network settings
What’s next on the roadmap?
1. Approving invoices
2. Entering spend and receive Money transactions
Date: 14 February, 2011
Version 2.06
New Features and improvements
- JSON support
Retrieve API responses from all endpoint in JSON format rather than XML. Try the API Previewer to see examples of the response format.
- Manual Journals – enter draft manual journals
- Items – add and update inventory items
- Invoices & Credit Notes – add item codes to invoices and credit notes to utilise prices and descriptions. You can also override any details of the items on individual invoices
- Retrieve PDF version of invoices in Xero (includes the branding themes that have been setup in Xero)
see Invoices and Credit Notes for more details. - Payments – you can now specify the reference field when adding payments
What’s next on the roadmap?
- Reporting APIs – we’re busy working with our beta testers to finalise this release. A public release will be available shortly.
- Approving invoices
- Entering spend and receive money transactions
Date: 15 December, 2010
Version 2.05
New feature and improvements
- Journals endpoint with ability to GET Journals
This data is essentially the same as the data you can retrieve manually in Xero from the “Adviser > Export GL Transactions” menu. See our Journals endpoint
- Invoice branding themes
Branding themes can now be applied to invoices created via our API.
We’ve added a BrandingTheme endpoint so you can retreive a list of branding themes an organisation is using. To apply a branding theme to an invoice you can include the BrandingThemeID element. See our updated Invoices endpoint documentation for more details.
If a BrandingThemeID is not specified on an invoice Xero will use the default branding theme for an organisation.
- Invoice URL links
You can now add URL links to invoices. If a URL link is specified, Xero will show a “view invoice in [app name]” link at the top of invoice.
To add these links you just need to add a URL element to your APi call. See our updated Invoices endpoint documentation for more details.
- API Rate Limiting
We’ve introduced a daily limit of 1000 API calls that a provider can make against a particular Xero organisation in a rolling 24 hour period. If you exceed this rate limit you will receive a HTTP 401 response. This limit is in addition to the 60 calls per minute per provider that is currently in place. The daily limit response message will look like the following.
oauth_problem=rate%20limit%20exceeded&oauth_problem_advice=please%20wait%20befor
e%20retrying%20the%20xero%20api
What’s next on the roadmap?
- Manual Journals – the ability to post draft manual journals.
- Reporting APIs – In Q1 2011 we’ll be releasing the first of our reporting endpoints. Cashflow and other speciaist reporting or analysis apps will be able to easily access a growing range of data from Xero. Our team is really excited at the possibilities this will open up to developers.
Date: 29 March, 2010
Version 2.03
New feature and improvements
- Support for private applications
Private apps use 2 legged OAuth and bypass the user authorisation workflow in the standard OAuth process. Private applications are linked to a single Xero organisation (chosen from a list of organisations you have standard user rights to).
Please read our developer information about setting up a private application
- Revoke access for applications
You can now revoke access to API v2 applications from inside the Xero application.
Go to the Xero Network Settings page (Settings > General Settings > Xero Network) to see a list of applications that have access to your organisation – they are listed at the top of the screen. You can click “disconnect” to revoke access.
Public applications still have access revoked automatically after 30 minutes of being authorised.
Private applications can be reinstated by generating a new consumer key and consumer secret from the Edit screen in the developer portal.
- Callback urls for public applications
You can now specify the oauth_callback parameter and redirect back to a different URL as long as it is still within your apps callback domain(you can now specify in your application settings in the developer portal). This is useful if you give your customers a unique subdomain to login to your application.
- Code samples
We have some cody samples in Ruby & .NET(coming soon) that you can use to get familiar with private apps. If you’d like to contribute code examples in other langauges please email them to network@xero.com
What’s next on the roadmap?
• Support for Partner applications is coming very soon. Partner apps are public applications that have been upgraded and given longer access to organisations without end users having to reauthorize access. This will enable Xero Network partners to use long term access tokens with single instance multi tenanted web applications.
• add draft manual journals, add spend money, receive money & transfer money transactions
• approve invoices via the API
Your feedback
We are always trying to deliver the features you are asking for so keep the feedback coming – please vote for what we should be working on next.
Xero Developer API v2 – Developer preview release
Date : 8 September, 2009
New features and improvements
- Authentication change to using OAuth only.
- initial OAuth support – all access tokens that expire after 30 minutes
- longer term access tokens will be available soon – see below for more info
- All API methods are now easier to use
- ordering of top level XML elements now doesn’t matter
- we’ve reduced the number of required elements for many API methods
- you can now filter results returned
- Better error messaging
- required xml elements that are missing will be returned
- required element values that are missing will be returned
- error codes will be returned for validation errors
- Easier to add invoices
- tax values on line items are no longer required e.g. just specify description, unit price (exclusive or inclusive of tax) & quantity
- if tax amounts are specified we expect an identical match to Xero calculations
- draft invoices can be updated
- Add draft invoices in a foreign currency
- Add payments to approved invoices
- Add draft Credit Notes (standalone)
- API call throttling – max 60 calls per minute per API provider
- Getting started with the Xero API is now easier
- No need to apply for an API key – just go to http://api.xero.com
- Anyone with a Xero user account can use our API previewer application to get familiar with our API and the user experience with using OAuth.
- There is no developer sandpit for API v2 – you can use your demo company as a sand pit Xero organisation during development.
- If you develop an application that suits expiring tokens then you don’t need to have your application approved. We still recommend you run a pilot before you go live.
Why is this titled a developer preview release?
This is not a feature complete release. We thought it would be useful to give you access to our latest stable build of v2 so you can start getting familiar with the new features and using OAuth if this is new to you.
In this preview release all OAuth tokens will expire after 30 minutes. We are working hard to make non expiring token support available as soon as we can and realise many of our Xero network partners and 3rd party developers will need this before migrating from v1. When we introduce this option for developers we’ll also have a mechanism within Xero to allow users to revoke access for any active access tokens.
Examples of applications that need longer term tokens include:
- server scripts that run as scheduled tasks to create draft invoices, sync contacts
- integrations that use the Xero API after a trigger (e.g. after a sale on your e-commerce site or an update of a contact in your CRM system
- online solutions that want to offer a “set and forget” approach to integration with Xero
We’re working hard to squash any remaining critical bugs over the coming weeks. Please let us know if have any issues – just drop a quick note to network@xero.com.
Getting started with API v2
Visit our API preview site http://api.xero.com to get familiar with the new features and changes.
FAQ’s
Why did we choose to go with OAuth?
What we think is great about OAuth is the improvement in user experience – users no longer have to go through the steps to generate a customer key in Xero and then paste this into a 3rd party application. Using OAuth we now have a suitable option to allow desktop and newly emerging device installed mobile applications to use our developer API as well.
Why do access tokens expire after 30 minutes by default?
We take the duty of protecting our customer’s data very seriously. Desktop applications that connect to Xero using our developer API need to have a small access window so you can have a higher degree of certainty that your data cannot be accessed by others if your computer is comprised. The limit has been set at 30 minutes to be consistent with the session timeout in the Xero web application.
As mentioned above we will soon have support for longer access tokens to developers that have web based applications or server scripts which have taken some extra steps to ensure access tokens are kept secure.
Isn’t OAuth adding a level of complexity that developers don’t need?
Most popular development languages already have OAuth wrapper classes available that make using OAuth very straight forward. In many cases once you’ve included the OAuth libraries only a few lines of code is required to add OAuth support to your application. There is a bit of learning required to get your head around the OAuth terminology but it’s nothing major. We’ve included some links to some good sites to check out which include detailed explanations of the workflow with OAuth and also code examples.
What’s next on the roadmap?
• Support for long term access tokens
• Bug fixes
• add draft manual journals via API
Your feedback
We’ve been using Uservoice for a while now to keep track of developer requests. If you’re not familiar with this – please go and have a look. This is a great way for us to know what you want us to build next and is also good way for you to see where your ideas rank amongst other developer’s requests. We are always trying to deliver the features you are asking for so keep the feedback coming.