Release Notes - Core API

To be notified as we release new features, subscribe to the Xero Developer mailing list.

March 27 2017

New Feature

January 27 2016

New Feature
  • Journals can now be retrieved on a cash basis by using the paymentsOnly=true parameter.

January 16 2016

Bug Fix
  • Removed the validation error returned when you include TotalDiscount on PUT/POST Invoices. Note: This does NOT mean that you can override the TotalDiscount amount - you still need to set discounts at the line item level.
  • Increased the speed of GET CreditNotes.

December 6th 2016

Bug Fix
  • Fixed the outstanding and overdue balances on Contacts with foreign currency transactions. All balances are now returned in base currency.

November 30th 2016

Bug Fix
  • Improved the speed of retrieving invoices with multiple allocations (payments, credit notes etc.)
  • Fixed a bug that caused foreign currency purchase orders with custom currency rates to crash the Xero UI

August 2nd 2016

Bug Fix
  • Improved the validation on Contacts when the max character length is exceeded for a particular element. Previously the error message was generic.

July 13th 2016

Bug Fix
  • Fixed a bug updating Invoice LineItems that incorrectly returned a 400 error any time a DiscountRate and LineAmount were provided on a LineItem.

July 13th 2016

Bug Fix
  • Fixed a bug in PUT/POST Invoices that resulted in a 200 response code but a generic validation error in the body. This bug occurred when the Contact had a default tracking category that had been deleted.

June 21st 2016

New Feature
  • DefaultSalesTax and DefaultPurchasesTax added to GET Organisation.

June 20th 2016

Bug Fix
  • Fixed a bug with Items that caused items to be returned with both a COGSAccountCode and Purchases AccountCode if they had been changed from untracked to tracked (or vice versa).

June 8th 2016

Bug Fix
  • You can no longer create public and partner apps with "Xero" in the name.

May 10th 2016

Bug fix
  • Enhanced the validation on PUT/POST Contacts to make it clearer when an archived Contact with the same ContactNumber already exists.

May 9th 2016

Bug fix
  • Fixed a bug in POST PurchaseOrders that removed the AccountCode from LineItems in some cases.

April 19th 2016

New Feature
  • Retrieve the Online Invoice Url for sales Invoices.

March 15th 2016

Bug fix
  • Fixed a bug in POST PurchaseOrders that was causing LineItems to duplicate in the Xero UI.

Release: March 8th 2016

New features and improvements
  • POST PurchaseOrders - You can now use the POST method to create and update purchase orders.

Release: January 22nd 2016

Bug fix
  • Fixed an issue that occured when updating Items using an ItemCode that didn't match the case of the value stored in Xero.

Release: January 21st 2016

New features and improvements
  • If-Modified-Since support for GET Accounts

Release: January 20th 2016

Bug fix
  • Fixed a bug (introduced in the previous release) that caused 400 errors when creating sales invoices using tracked items and not specifying the account code (i.e. relying on the default account code).

Release: January 18th 2016

New features and improvements Coming Soon
  • POST (Update) PurchaseOrders.

Release: January 12th 2016

New features and improvements

Release: December 15th 2015

Bug fix
  • POST Items - Previously, the AccountCode in PurchaseDetails was being nulled when updating non-tracked items with <COGSAccountCode i:nil="true" /> in the request. As raised in Community.

Release: December 11th 2015

New features and improvements Coming Soon (Jan 2016)
  • PUT &nsp; POST PurchaseOrders.

Release: November 30th 2015

New features and improvements
  • Updated the validation rules for Top Level Domains (TLDs) when setting the Url field on the Invoices endpoint.

Release: November 23rd 2015

Date: November 23rd, 2015 New features and improvements
  • GET LinkedTransactions now returns the SourceTransactionTypeCode allowing you to see if the billable expesnse was created from an invoice (ACCPAY) or bank transaction (SPEND).

Release: November 18 th 2015

New features and improvements Bug Fixes
  • Added validation to prevent both purchase account code and cogs account code being added to a tracked item.
  • Added validation to prevent deleted tax rates being used on an item.

Release: November 16th 2015

Bug Fixes
  • Fixed a bug that prevented users from regenerating their consumer key and secret in app.xero.com.
  • Fixed a bug that caused 500 errors for a small number of organisations on GET Users.

Release: November 5th 2015

New features and improvements
  • Delete payments on credit notes, prepayments and overpayments.
Bug Fixes
  • Fixed an issue that prevented US payroll tax payment journals being returned.

Release: November 3rd 2015

New features and improvements

Release: November 2nd 2015

New features and improvements You can set Report Codes for AU & NZ orgs using the Setup endpoint.

Release: October 20th 2015

New features and improvements
Tracked inventory is now supported via the Items endpoint.
  1. Create and update tracked inventory items.
  2. Retrieve the quantity on hand total cost pool for tracked inventory items.
  3. Update the Name and Purchase description of both tracked and untracked items.
Coming Soon The ability to delete tracked and untracked items.

Release: October 14th 2015

Bug Fixes
  1. Fixed a 500 error being returned when phone number length exceeded 50 characters on Contacts
  2. Improved error messaging on Payments
  3. Updating your email address in Xero will now display correctly in app.xero.com and developer.xero.com

Release: September 14th 2015

New features and improvements
  • You can now update the payment terms on Contacts.
Bug Fixes
  • Fixed a bug that stopped payment terms from being returned on GET Contacts when the Day was set to zero (e.g. 0 days after invoice date).

Release: September 11 2015

New features and improvements Coming Soon
  • Support for the If-Modified-Since header and using multiple filters in combination.

Release: September 1st 2015

New features and improvements
  • The Accounts endpoint now returns the BankAccountType which allows you to tell the difference between Paypal, credit card and regular bank accounts.
Bug Fixes
  • Fixed a bug that always caused IsDemoCompany to return false on the Organisation endpoint.

Release: August 14th 2015

New features and improvements
  • Prepayments and overpayments that have been allocated to invoices are now returned on the Invoices endpoint when using paging.

Release: July 28th 2015

New features and improvements
  • LineItemIDs are now returned on paged Invoices

Release: July 27th 2015

New features and improvements
  • BankAmount on Payments - The payments endpoint now exposes BankAmount, the payment amount after conversion to the bank's currency.
Coming Soon
  • LineItemIDs on GET paged invoices

Release: July 22nd 2015

New features and improvements
  • LineItemIDs on Invoices - The invoices endpoint now exposes LineItemIDs when getting individual invoices and accepts them on updates. This is an important change to support the upcoming billable expenses feature. See our community post for more details.
Coming Soon
  • LineItemIDs on GET paged invoices

Release: July 7th 2015

New features and improvements
  • Cash basis Profit & Loss and Balance Sheet reports can now be retrieved using the paymentsOnly parameter

Release: June 17th 2015

New features and improvements

Release: May 4th2015

New features and improvements

Release: April 21st, 2015

Bug Fixes
  • Fixed a bug that prevented the case of a Contacts' Name from being updated.
  • Fixed a bug on the Journals endpoint that prevented some types of journals from being returned (fixed assets, reconciliation adjustments, conversion balances).

Release: March 26th 2015

New features and improvements What’s next?
  • Inventory accounting enhancements

Release: March 25th 2015

New features and improvements
  • Create refunds for Overpayments and Prepayments using the payments endpoint
What’s next?
  • More Inventory accounting enhancements

Release: March 24th 2015

New features and improvements
  • New validations to support tracked inventory items
  • New Account Type INVENTORY
What’s next?
  • More Inventory accounting enhancements

Release: March 17th 2015

New features and improvements
  • Overpayments Allocations. PUT Overpayments/{OverpaymentID}/Allocations
  • Prepayments Allocations. PUT Prepayments/{PrepaymentID}/Allocations
Bug Fix
  • Fixed a bug that stopped allocated credit notes being returned when retrieving multiple invoices
What’s next?
  • More Inventory accounting enhancements

Release: March 11th 2015

New features and improvements What’s next?
  • Create & update Prepayments and Overpayments

Version 2.90

Date: March 4, 2015
New features and improvements
  1. GET Journals and ManualJournals - The TrackingOptionID is now returned on journal lines.
  2. GET ExpenseClaims - Tracking details are now returned on receipt line items when retrieving an individual expense claim.
Bug fixes
  1. Fixed a 500 error for TaxComponent Names longer than 50 characters on PUT/POST TaxRates
What’s next?
  1. GET Prepayments and Overpayments

Version 2.89

Date: February 26, 2015
New features and improvements
  1. PUT/POST TaxRates - The MOSSSALES ReportTaxType is now supported for create and update (UK organisations only).
strong>What’s next?
  1. Tracking details on expense claims

Version 2.88

Date: February 25, 2015
New features and improvements
  1. POST Accounts - You can update the status of an Account from ACTIVE to ARCHIVED.
What’s next?
  1. MOSS VAT tax rate support (UK only)

Version 2.83

Date: January 22, 2015
New features and improvements
  1. GET Journals - The SourceID and SourceType are now returned. This enables you to link journals with source transactions.
Bug fixes
  1. GET BankTransactions paging - Tax inclusive bank transactions now return tax inclusive unit amounts when paging is used.
  2. GET BankTransactions paging - ItemCode is now included on LineItems when paging is used.
  3. GET BankTransactions paging - UnitAmount is now 2DP by default when paging is used.

Version 2.79

Date: January 13, 2015
New features and improvements
  1. GET ManualJournals - optional paging of results with journal line details included.
Bug fix
  1. BankTransactions paging - Tax inclusive bank transactions now return tax inclusive line amounts when paging is used.

Version 2.78

Date: January 7, 2015
New features and improvements
  1. GET BankTransactions - optional paging of results with line item details included.

Version 2.74.3

Date: December 8, 2014
New features and improvements
  1. Payments - delete a payment.

Version 2.73

Date: November 25, 2014
New features and improvements
  1. Account Number - Retrieve and update the Account Number on Contacts.
  2. Default Tracking Categories - Retrieve and update the default tracking categories on Contacts
What’s next?
  1. Deleting Payments on Invoices

Version 2.72

Date: November 20, 2014
New features and improvements
  1. Internal fixes and improvements to some of our internal logging system
What’s next?
  1. Contact Account Number

Version 2.71

Date: November 17, 2014
New features and improvements
  1. Tracking Categories - Create and update tracking categories and options.
What’s next?
  1. Contact Account Number

Version 2.69

Date: November 4, 2014
New features and improvements
  1. Contacts - Default BrandingTheme is now returned on GET requests.
  2. Reports - The Profit & Loss Report now supports two tracking categories.
  3. CreditNotes - You can now create zero total credit notes.
What’s next?
  1. Add and update tracking categories and options
  2. Contact Account Number

Version 2.68

Date: October 22, 2014
New features and improvements
  1. ContactGroups - Add multiple contacts to a contact group in a single request.
  2. ContactGroups - Remove all contacts from a contact group.
What’s next?
  1. Add and update tracking categories and options

Version 2.67

Date: September 23, 2014
New features and improvements
  1. ContactGroups - a new endpoint to create and update contact groups.
  2. Add a contact to ContactGroups
  3. Remove a contact from ContactGroups
What’s next?
  1. Add and remove multiple contacts form ContactGroups

Version 2.66

Date: Sept 22, 2014
Bug fix
  1. My Applications - You can now add callback domains where the first character is a number (e.g. 1app.com)
  2. My Applications - Fixed the name validation on creating a private application. The application name must be unique amongst the apps registered to a developer.
  3. Journals - When a connection is authorised by a user that has 'no reports' access a 401 error is returned (previously a 500 was returned).
What’s next?
  1. Add/update Contact Groups
  2. Add/remove Contacts to/from Contact Groups

Version 2.65

Date: Sept 1, 2014
Bug fix
  1. Invoices - Fine-tuned the line amount calculation when a discount rate us applied. Previously certain edge cases were causing 400 errors due to rounding.
What’s next?
  1. Add/Update Tracking Categories

Version 2.64

Date: Aug 15, 2014
Bug fix
  1. Contacts - Corrected inconsistent behaviour when retrieving contact persons in the Demo Company.
What’s next?
  1. Add/Update Tracking Categories

Version 2.63

Date: Aug 13, 2014
New features and improvements
  1. Contacts - update to support a default sales account and default purchases account on GET, PUT and POST.
Bug fixes
  1. Corrected the default (2 decimal place) rounding on UnitAmount when calculating LineAmount on line items.
  2. My Apps - fixed the bug preventing updates to public and private apps with no callback domain specified.
What’s next?
  1. Add/Update Tracking Categories

Version 2.62

Date: Jul 30, 2014
New features and improvements
  1. GET Tracking Categories - a new opt-in parameter to retrieve ARCHIVED tracking categories & options and a Status element now is returned for tracking options.
What’s next?
  1. Add/Update Tracking Categories

Version 2.61

Date: Jul 28, 2014
Bug fixes
  1. Expense claims now return the <User> element even after the user has been deleted from Xero.
  2. SUBMITTED expense claims that contain a receipt with a deleted <AccountCode> will now return successfully.
  3. Fixed an issue with tracking categories in the P&L report. Previously, if an organisation had deleted tracking categories and created new ones multiple times they were not being picked up by the report.
What’s next? 1.Add/Update Tracking Categories

Version 2.60

Date: Jul 18, 2014
New features and improvements
  1. Implemented a change to how we process concurrent requests when applying payments which makes it more efficient and more robust.
What’s next?
  1. Add/Update Tracking Categories

Version 2.59

Date: Jul 15, 2014
New features and improvements
  1. Support for setting attachments to be included with online invoices. Learn more
  2. GET Organisation - SalesTaxBasis and SalesTaxPeriod added to the Organisation endpoint
What’s next?
  1. Add/Update Tracking Categories

Version 2.58

Date: July 9, 2014
Bug fixes
  1. Removed the 'Date Imported into Xero' Column from the BankStatement report.
What’s next?
  1. Add/Update Tracking Categories

Version 2.57

Date: July 7, 2014
Bug fixes
  1. Improved validation and error messaging on the Accounts endpoint when invalid Type values are used.
  2. Improved error messaging when uploading invalid public certificates during app registration.
  3. Resolved issues around specifying multiple callback domains (Partner apps only).
What’s next?
  1. Add/Update Tracking Categories

Version 2.56

Date: Jul 3, 2014
Bug fixes
  1. An issue affecting invoice line items with zero quantities on tax inclusive invoices has been resolved.
What’s next?
  1. Add/Update Tracking Categories

Version 2.55

Date: Jul 1, 2014
New features and improvements
  1. Support for 4dp on line items. Learn more
Bug fixes
  1. Resolves a fix for issues with tax inclusive issues with a line item.
What’s next?
  1. Add/Update Tracking Categories

Version 2.54

Date: June 9, 2014
Bug fixes
  1. Allow ampersand in file attachments
  2. Removed HasAttachments from nested contacts
  3. Added fix for Repeating Invoice attachments
What’s next?
  1. Invoice improvements - be able to retrieve online invoice urls

Version 2.53

Date: May 29, 2014
New features and improvements
  1. Bank Transactions - update to support ItemCodes on GET,PUT POST methods
  2. Attachments - add support for attachments on Accounts, Bank Transactions, Bank Transfers, Contacts, Credit Notes, Invoices (upgraded to all status codes) , ManualJournals & Repeating Invoices
Bug fixes
  1. Resolves an issue with updating tax rates.
What’s next?
  1. Invoice improvements - be able to retrieve online invoice urls

Version 2.52

Date: May 28, 2014
New features and improvements
  1. POST Setup (beta) - new endpoint to setup chart of accounts, conversion date and conversion balances. Learn more
What’s next?
  1. Enhanced attachments support

Version 2.51

Date: May 12, 2014
New features and improvements
  1. POST TaxRates - added support for updating tax rates
Bug fixes
  1. Contacts and Repeating Invoices - Resolves an issue with the new payment term TYPE for day(s) after the end of the bill month not being shown if used.
What’s next?
  1. Conversion Balances

Version 2.50

Date: May 5, 2014
New features and improvements What’s next?
  1. Ability to update TaxRates

Version 2.49

Date: Apr 30, 2014
Bug fixes
  1. Resolves issue with editing private applications
  2. Show validation error when making payments using non-existent invoice number
  3. Resolves an issue with expense claims status changes
What’s next?
  1. Conversion Balances

Version 2.46

Date: Mar 31, 2014
New features and improvements
  1. GET Repeating Invoices - ability to retrieve repeating invoices templates.
Bug fixes
  1. Resolves API blocking invoice dates before 2006
  2. Allowing duplicate private applications if a different provider
What’s next?
  1. Ability to replace a chart of accounts

Version 2.45

Date: Mar 25, 2014
New features and improvements
  1. GET Users - an EmailAddress element is now return in the response for each user.
Bug fixes
  1. Resolves an issue with foreign currency invoice payments
  2. Resolves an issue with JSON responses for invoice overpayments
What’s next?
  1. Retrieving repeating invoices

Version 2.44.2

Date: Mar 20, 2014
Bug fixes
  1. Fix for invoice filters using Contains, StartsWith, and EndsWith
  2. Resolves an issue with filtering BankTransactions on Contact.Name
  3. Resolves an issue with Updating ACCPAY invoices without lineitems
What’s next?
  1. Retrieving repeating invoices

Version 2.44.1

Date: Wed 19 March, 2014
Bug fixes
  1. GET Invoices - resolves an issue with applying date range filters on the Date element
What's next ?
  1. Retrieving repeating invoices

Version 2.44

Date: Tue 18 March, 2014
New features and improvements
  1. GET Invoices - optional paging of results with line item details included
Bug fixes
  1. GET Invoices - resolves an issue with the HasAttachments element
What's next ?
  1. Retrieving repeating invoices

Version 2.43

Date: Thu 27 Feb, 2014
New features and improvements
  1. PUT Payments - be able to mark payments as reconciled
  2. POST Invoices - be able to set ExpectedPaymentDate and PlannedPaymentDate
  3. GET Contacts - be able to apply an additional flag to return archived contacts as well (excluded by default)
Bug fixes
  1. Be able to retrieve archived contacts rather than get returned a HTTP 404
What’s next?
  1. Option for paged invoices with line item details

Version 2.42

Date: Feb 26, 2014
New features and improvements
  1. PUT/POST BankTransfers (beta) - support for creating bank transfers via the API
What’s next?
  1. Paging on Invoices

Version 2.41

Date: Feb 20, 2014
New features and improvements
  1. PUT Accounts - support for creating bank accounts via the API
Bug fixes
  1. GET Contacts - bill payment terms showing correct payment terms
  2. Ensuring a HTTP 401 code is returned when trying to the Reports endpoint with the new "No Reports" user role. Was returning a 403 in error.
What’s next?
  1. Bank Transfers - support for creating bank transfers

Version 2.40

Date: Feb 17, 2014
New features and improvements
  1. GET Reports - new standard user role without report access is enforced for API calls
What’s next?
  1. PUT Accounts - support for creating bank accounts via the API

Version 2.39.1

Date: Feb 5, 2014
Bug fixes
  1. Resolves an issue with performance of GET BankTransactions
What’s next?
  1. Accounts – add support for creating bank accounts

Version 2.39

Date: Feb 4, 2014
New features and improvements
  1. BankTransactions : create prepayments and overpayments
What’s next?
  1. Accounts – add support for creating bank accounts

Version 2.38

Date: Jan 27, 2014
New features and improvements
  1. Expense Claims - PaymentDueDate and ReportingDate elements are now returned on GET ExpenseClaims
  2. Payments element now returned when retrieving individual Expense Claim
  3. My Applications - added support for multiple call back domains

Version 2.37

Date: Jan 16, 2014
New features and improvements
  1. Contacts - ability to add additional contact people for a contact record
  2. BankTransactions - ability to mark transactions as reconciled
What’s next?
  1. Accounts – add support for creating bank accounts

Version 2.36

Date: Dec 12, 2013
New features and improvements
  1. PUT Accounts (beta) – The Accounts endpoint now has support for creating standard accounts
What’s next?
  1. Accounts – add support for creating bank accounts

Version 2.35

Date: Nov 21, 2013
New features and improvements
  1. PUT TaxRates - The TaxRates endpoint now supports creating new tax rates
What's next?
  1. Accounts - add support for creating new accounts

Version 2.34

Date: Nov 14, 2013
New features and improvements
  1. 1099 Reports for US users can now be retrieved for prior years.
Bug fixes
  1. POST Attachments - add support for capitalised file extensions e.g. filename.PDF is now supported
What’s next?
  1. TaxRates - ability to create new tax rates

Version 2.33

Date: Nov 11, 2013
New features
  1. POST/PUT ManualJournals - manual journals with more than 100 line items are now supported
  2. GET TaxRates - full details of single tax component tax rates are now shown
  3. GET Reports - updates to return finalised GST Reports in addition to the existing published reports for NZ organisations.
Bug fixes
  1. POST/PUT ManualJournals - totals in the Xero UI for tax inclusive manual journals generated via the API are now showing correctly.
  2. GET xxxx/Attachments - port number has been removed from the Url element value
What’s next?
  1. 1099 Report - ability to view prior year reports

Version 2.32

Date: October 31, 2013
New features and improvements
  1. POST/PUT Invoices - added support for discounts on line items for Sales (ACCREC) invoices
Bug fixes
  1. GET BankTransactions - issue filtering by contact name is resolved
  2. GET ExpenseClaims - account codes now shown on line items for receipts on individual expense claims
What’s next?
  1. Updates to POST/PUT BankTransactions to support creating overpayments, prepayments and transfers

Version 2.31.1

Date: October 22, 2013
Bug fixes
  1. Resolves an issue with JSON dates not formatting the same way as previous versions.
What’s next?
  1. Support for discounts on line items

Version 2.30

Date: September 26, 2013
New features and improvements
  1. GET Contacts - optional paging of results
What’s next?
  1. Support for discounts on line items

Version 2.29

Date: September 17, 2013
New features and improvements
  1. Details of transfers, prepayments and overpayments are now returned for GET BankTransactions. The ability to POST these will come in a future update.
Bug fixes
  1. Resolves an issue with filtering GET TrackingCategories
What’s next?
  1. Paging for contacts, adding support for discounts on PUT/POST invoices

Version 2.28

Date: September 12, 2013
New features and improvements
  1. You can now create part or full refunds for credit notes via the Payments endpoint
Bug fixes
  1. Contacts created via the API now strip out double white spaces to be consistent with the Xero App
  2. Resolves an issue with updating manual journals that used inclusive amounts
What’s next?
  1. BankTransactions improvements, adding support for discounts on PUT/POST invoices

Version 2.27.1

Date: September 3, 2013
Bug fixes
  1. Fix for contacts not found to return HTTP 404's

Version 2.27

Date: September 2, 2013
New features and improvements
  1. Tax rate components for custom defined tax rates are now retrievable - see GET Tax Rates
  2. Default payment terms for an organisation are now retrievable - see GET Organisation
  3. The Profit and Loss and Balance Sheet reports can now be retrieved using the standard layout rather than a customised user specific version - see Profit and Loss Report and Balance sheet Report
  4. More details on contacts are now returned when retrieving individual contacts - see Contacts
  5. Contact balances are now returned for individual contacts - see Contacts
  6. The ExpectedPaymentDate is now returned when retrieving a specific sales invoice if this value has been set. Populating this element via the API will be available in a future release. See Invoices
  7. The PlannedPaymentDate is now returned when retrieving a specific bill. Populating this element via the API will be available in a future release. See Invoices
Bug fixes
  1. Fix for some errors in API History showing as 5xx's as well as 400's.
What’s next?
  1. Credit Note refunds, bank transaction improvements

Version 2.26

Date: August 22, 2013
Bug fixes
  1. Resolve issues with rendering PDFs when using custom doc x templates
  2. Resolve stability issues with retrieving PDFs of invoices
  3. Resolve bug with deleting application in some browsers
What’s next?
  1. Reports, contacts & invoice improvements

Version 2.25.2

Date: May 28, 2013
New features and improvements
  1. Public release of the Xero Payroll API
What’s next?
  1. Credit Note refunds, report improvements, bank transaction improvements

Version 2.24.4084

Date: May 2, 2013
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

Version 2.24

Date: Apr 23, 2013
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

Version 2.23

Date: Mar 25, 2013 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

Version 2.22

Date: Mar 11, 2013
New features and improvements
  1. 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

Version 2.20

Date: Dec 10, 2012
New features and improvements
  1. 1099 report for US Users
What’s next?
  1. Credit note improvements

Version 2.19

Date: Oct 30, 2012
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
  1. OAuth signatures now support both the OAuth 1.0a and 1.0 final spec (1.0 final spec has a change for PUT requests)
  2. Filenames are now correctly showing when attachments on invoices and receipts have spaces What’s next?
    1. 1099 Report for US users

Version 2.174

Date: Oct 11, 2012
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
  1. 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

Version 2.17

Date: Sept 19, 2012
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

Version 2.16

Date : July 16, 2012
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?
  1. XML File Import for Conversions

Version 2.15.39

Date : May 14, 2012
Bug Fixes
  1. Rounding issue on Manual Journals - A rounding calculation on manual journals validation was preventing the entry of Manual Journals in certain circumstances.
  2. 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.
  3. 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’s next?
  1. Support for attachments on Accounts Payable invoices
  2. Mark invoices as been sent to a contact

Version 2.15

Date : April 17, 2012
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 ?
  1. Support for attachments on Accounts Payable invoices
  2. Mark invoices as been sent to a contact

Version 2.14

Date : 20 February, 2012
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?
  1. Approved manual journals
  2. Application permissions
  3. Full support for discounts

Version 2.13

Date : 19 December, 2011
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?
  1. Performance Improvements
  2. Approved Journals

Version 2.12.127

Date : 24 November, 2011
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?
  1. Expense Claims
  2. Performance improvements & AP invoice file attachments
  3. Approved manual journals

Version 2.12

Date : 08 November, 2011
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.

Version 2.11

Date : 2 August, 2011
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

Version 2.09

Date : 14 June, 2011
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

Version 2.08

Date : 23 May, 2011
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.

Version 2.07

Date : 23 March, 2011
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

Version 2.06

Date: 14 February, 2011
New Features and improvements
  1. 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.
  1. Manual Journals - enter draft manual journals
  2. Items - add and update inventory items
  3. 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
  4. 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.
  5. 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

Version 2.05

Date: 15 December, 2010
New feature and improvements
  1. 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
  1. 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.
  1. 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.
  1. 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.

Version 2.03

Date: 29 March, 2010
New feature and improvements
  1. 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
  1. 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.

  1. 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.
  1. 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
  1. 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
  2. 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
  3. 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
  4. 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
  5. Add draft invoices in a foreign currency
  6. Add payments to approved invoices
  7. Add draft Credit Notes (standalone)
  8. API call throttling - max 60 calls per minute per API provider
  9. 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.