Skip to main content

Changes to the API

Xero regularly updates its API’s to support new features or deprecate old ones. This page keeps track of all future and previous changes that have occurred to the API, and what you need to do to ensure your integrations keep working.

Last updated: 11 August 2025

Upcoming Changes

These changes may have impacts to how integrations are currently calling the API. Please update your integration accordingly.

August - October 2025

  • Practice Manager 3.0 & 3.1 – We’re migrating from using the Folder field to a new Tag field within the client record’s Notes section in the GET /clients/{id} endpoint. To further unify our practice management tools, we’re moving to Tags in Xero Practice Manager (XPM), leveraging existing Xero HQ functionality. Existing folder-based notes will be automatically migrated. The Folder field within the client record’s Notes section will now return NULL, and a new Tag field will contain associated tags. If you use GET /clients/{id}, update your integration to handle the new Tag field and NULL values in the Folder field. This is now the default experience for all UK XPM accounts. These changes will apply to practices as they transition to the Single Client Experience. This will be delivered through an iterative rollout:

    • Phase 1 – 18 August 2025 - Includes practices that: Do not use Tax Access Restrictions on the client record, and do not use the Xero Tax (XT) bundle.

    • Phase 2 - Includes practices that: Do use Tax Access Restrictions and/or are on the XT bundle

    • General Availability - October 2025

  • Accounting API - We are introducing a change to retrofit an authorisation check, which will mask US Tax Numbers (with only the last 4 digits revealed) for contacts retrieved via the Contacts API endpoint for Standard role users. Standard users will still be able to update the tax number.

  • Accounting API - We are improving the validation on accounting document IDs for the Payments and /*/allocations endpoints to only find the document for the given ID if it's type matches the expected type. Eg. you can no longer create a payment for a credit note, prepayment or overpayment by using the InvoiceID field. The apps which are using the wrong document types in their requests will start to see NOT FOUND. Currently the request succeeds but creates the payment or allocation against a document they might not be expecting.

  • NZ Payroll API - NZ Payroll customers will be migrating to new features to better manage leave and compliance with the Holidays Act. These changes will require some restrictions to be implemented which may affect some customers. The changes relate to behaviour locking Salary & Wages at the time of the migration, and a limitation on the assignment of pay frequencies.

    Once an Organisation has adopted new features to better manage leave and compliance with the Holidays Act, the following API behaviour will change:

    Change to Salary & Wages locking behaviour

    PUT: /payroll.xro/2.0/Employees/{EmployeeID}/salaryAndWages

    DELETE: /payroll.xro/2.0/Employees/{EmployeeID}/salaryAndWages

    Currently SalaryAndWages are only locked after they are included in a pay run. However, because we need to use the SalaryAndWages record to convert leave units from hours into weeks / days, if the SalaryAndWages record is the one that is in effect for the employee on the date of migration, that SalaryAndWages will now be locked regardless if used in a pay run or not and can not be updated or deleted

    Change to Employment

    POST: /payroll.xro/2.0/employees/{EmployeeID}/employment/

    Currently pay frequencies can be assigned to employees, but after the employee’s leave units have been converted.

    Setting Fixed term end date (Immediately after release): It will be possible to set the fixed term end date for employees who have not yet been migrated.

    Assigning Pay Frequency (Once migrated): if the pay calendar’s end date is before the date of conversion, it won’t be possible to assign it to that employee.

    Change to response for employee

    GET: /payroll.xro/2.0/Employees

    GET: /payroll.xro/2.0/Employees/{EmployeeID}

    Currently the employee’s details do not include the date from which the new units are applicable, but after the employee’s leave units have been converted, the employee’s details will include their Effective date.

    Change to pay runs

    POST: /payroll.xro/2.0/payRuns

    Once migrated

    It won’t be possible to have a scheduled pay-run prior to the migration date.

    It won’t be possible to assign an employee a pay-frequency that would include them prior to their migration date.

    Change to employee leave

    POST: /payroll.xro/2.0/employees/{EmployeeID}/leave/

    PUT: /payroll.xro/2.0/employees/{EmployeeID}/leave/

    Once migrated

    Leave will not be able to be processed in a pay-run that is before the employee’s migration date. Any historic leave requests will be processed in a pay-run after the employee’s migration date.

November 2025

  • AU Payroll API - Effective November 10th, 2025, we are updating the Payroll AU API endpoint for pay runs (specifically POST PayRuns) to process only a single pay run per request. While the request contract will continue to accept an array of pay runs, starting from effective date above, requests containing more than one pay run will be rejected with HTTP status code 400 and an accompanying message. There are no changes to the response contract.

Ongoing

  • We will be deprecating use of the Employees endpoint in the Accounting API. We're doing this because the global Payrun product is being discontinued in our Xero Global Edition, and use of the Employee contact type will no longer be available. If you use this endpoint, please no longer use it to support creating or updating contact information.

Change History

All updates that have been made to our API's, including new features.

May 2025

  • Accounting API - We added 3 new fields to the response of the BatchPayments endpoints to allow API consumers to detect FX scenarios, and ensure that Amounts from the response are denominated in the correct currencies in their own systems:

    • BatchPayment.Account.CurrencyCode - CurrencyCode e.g. GBP of the account used to make the payment(s).

    • BatchPayment.Payments[].Invoice.CurrencyCode - CurrencyCode e.g. EUR of the Invoice the payment was made against

    • BatchPayment.Payments[].BankAmount - The absolute value of the amount being paid in the currency of the account (read-only)

  • Accounting API - We fixed a bug where DiscountAmount and DiscountRate properties on existing LineItems are saved with incorrect values after an Invoice update operation where LineItems are not included in the request.

  • Accounting API - We added a new value, SIMPLE, to the Class enum for the Organisation Endpoint. This is to support you and your clients with MTD for IT. Our non-VAT Xero Cashbook plan is evolving into Xero Simple

April 2025

  • UK Payroll API - We added neonatalcare leave earnings types to EarningsRate type. This rate can appear on the following endpoints: EarningRates, EmployeeStatutoryLeaveBalance, EmployeeStatutoryLeaveSummary. If you use the UK Payroll API via one of our public SDKs, it is important you update to the latest version to support this new type.

March 2025

  • UK Payroll API - We are added two additional fields to the NI Category type used in the endpoints GET Employee by ID and POST Employment. These fields relate to specific NI category letters. Users setting one of these categories through the Payroll API should provide a valid value for the relevant field. Requests without the field populated will generate an error result after 1 June 2025.

    • `dateFirstEmployedAsCivilian` is applicable to category the veterans category (V).

    • `workplacePostcode` applies to Freeport and Investment Zone categories (F, I, L, S, N, E, D or K).

  • Practice Manager 3.0 & 3.1 – For UK XPM accounts we migrated from using the Folder field to a new Tag field within the client record’s Notes section in the GET /clients/{id} endpoint. To further unify our practice management tools, we moved to Tags in Xero Practice Manager (XPM), leveraging existing Xero HQ functionality. Existing folder-based notes have been automatically migrated. The Folder field within the client record’s Notes section will now return NULL, and a new Tag field will contain associated tags.

February 2025

  • Finance API - We removed some fields from the CashValidation API responses that were previously marked as unused, from the the API response itself. The fields removed are:

    • bankStatement.statementLines.dataSource.indirectBankFeed

    • bankStatement.statementLines.dataSource.indirectBankFeedPos

    • bankStatement.statementLines.dataSource.indirectBankFeedNeg

  • Accounting API - We added a small piece of validation to enforce a 100 character limit when creating Tracking Category options. We now check the name length and return a 400 message explaining why the request failed. We previously returned a 500 message with no explanation.

  • AU Payroll API - A new validation has been introduced on the Post Employees endpoint to prevent employment termination if the employee has any unprocessed leave requests that have not yet been included in a pay run.

  • Practice Manager API - We added new API end points to support pagination in the Client list. This will assist 3rd Party App integrators with customers who have large client lists and who have previously come across pages timing out. The response is similar to the current unpaginated list, except that it is presented with pagination and a simple data format - it does not include Contacts, Notes, Groups/Relationship.

September 2024

  • Accounting API - The Accounts endpoint now allows creating and updating bank and credit card accounts.

  • Accounting API - Changes to validation error messages in the Payments API. When a payment is submitted with a payment date during an Organisation's lock date, the validation message was missing whitespace between the word 'date' and the date itself. For example, an error message may have been returned as "Organisation accounts are locked on the specified payment date18/08/24".  There will now be space between the word "date" and the payment date, i.e.  "Organisation accounts are locked on the specified payment date 18/08/24".

  • UK Payroll API - We have added a new field to the Employee Leave Types Endpoint. We have added the ScheduleOfAccrualDate FIELD to the Payroll UK - Employee Leave Types Endpoint. This is an extension of the existing OnAnniversaryDate functionality that enables an employee’s leave to accrue based on a custom date. This will only be applicable when the scheduleOfAccrual is set to “OnAnniversaryDate” and a value is specified for ScheduleOfAccrualDate.

  • Accounting API - New US Sales Tax fields have been added to the Credit Notes and Invoices Endpoint. New functionality has been added to specify US Sales tax level fields when retrieving auto tax credit notes and invoices. Public API users will see the following new fields when fetching an auto tax credit note or invoice: 

    • InvoiceAddresses

    • Taxability 

    • TaxBreakdown 

    • SalesTaxCodeId

  • Accounting API – We will be enforcing high volume threshold limits to key endpoints in the Accounting API, set to come into force from 1 September 2024. This will help to enhance the stability of our platform and provide a better experience for all users. These limits are similar to the limit that is already in place for the GET Payments endpoint. The proposed threshold limit will only be applicable to GET requests:

    • That requires more than 100k documents to be retrieved, processed, filtered, or ordered.

    • It’s important for you to know that the limit applies to the amount of data that the system needs to process, not the number of results you request.

    • To see if your request currently exceeds a limit, a new warning message is included in the response.

    • To ensure your app performs efficiently, use paging, optimised filtering and ordering combinations to only read the data needed to perform an operation, so you can continue to retrieve data as expected. Please refer to the High Volume Threshold documentation for more information, and a full list of all endpoints that will be impacted and how to improve your requests. Please refer to the Threshold FAQ for additional questions.

August 2024

  • Accounting API - Credit Notes currently have `SentToContact` as a boolean read only field. This field will be changed on Monday, the 26th of August 2024 to be writable. However, a credit note can only be marked `SentToContact` if it is in an Awaiting Payment or Paid state. Please ensure you check if you are correctly using `SentToContact`. Setting it as`false` will mark the credit note unsent. Passing `null` is OK as the system won't change the credit note.

July 2024

  • NZ Payroll API – We’re making changes to support additional compliance with the Holidays Act (2003) within Payroll. The changes include adding an engagement type for an employee, recording custom accrual dates on employee leave types, and adding the ability for employees to record and track leave in units other than hours. This changes multiple endpoints in NZ Payroll, full details are available on our website.

  • Accounting API - We have enabled apps to specify a custom pagesize using the pagesize parameter up to a maximum pagesize of 1000 for all endpoints that currently support paging (with the exception of Journals endpoint). The default pagesize will remain at 100. When pagination is used, we now return a pagination object in the response that includes: page, pageSize, pageCount, itemCount.

June 2024

  • Files API - Two new fields, 'Name' and 'Size' have been added to the object association endpoint- /associations/{objectId}. The endpoint was also previously updated to include 'SendWithObject' in this response.  This was missing in the documentation, but has now been updated.

  • UK Payroll API - We’re making changes to how employee's leave balances update in UK Payroll. After the 18th of June, the balance will now reflect their correct balance automatically on the 1st January, or the employee's anniversary date for accrual methods "Beginning of calendar year" and "On employee anniversary" respectively, even if a pay run for that date has not yet been posted.

  • Xero App Store API - We’ve been working on our pricing models to give you more options to mix and match based on your needs  and we wanted to keep you informed of what's currently available:

    • Fixed: Charge a consistent monthly amount.

    • Metered: Bill based on usage during the billing period.

    • Seat: Align pricing with the number of users.

    • Simple: Add optional extras and monthly.

    More information on how you can build to these models can be found at  Xero App Store API and Xero App Store subscriptions pricing.

May 2024

  • Accounting API - We’ve added new "Disallowed Expenses" tax rates for use in the Singapore market, which take advantage of a new feature that automates the creation of Journal entries for non-recoverable tax amounts. These new rates now reflect the GST tax rate (for the years they are relevant to). Review the new tax rates.

  • Accounting API - We have added a new TaxNumber type field to the Contacts endpoint, which will indicate the regional type of tax number that is being returned. This will bring parity to our UI, and US types will be masked for Standard role users wherever a contact is returned (ie. GET Contacts, Invoices, etc). Standard users will still be able to update the tax number.

  • Xero App Store API - We’ve added the “currentPeriodStart” field to the GET Subscription endpoint. This pairs with the currentPeriodEnd field so you can see both the Start and End dates of the current subscription period.

  • UK Payroll API - We’re adding the ability for employees to be assigned a working pattern, improving payrun calculations for employees working non-standard patterns. What was announced in the February 2024 newsletter has changed. This will initially be optional, but will become mandatory no earlier than May 2024. UK Payroll Working patterns details

  • NZ Payroll API - We’re adding the ability for employees to be assigned a working pattern, improving payrun calculations for employees working non-standard patterns. This will initially be optional, but will become mandatory no earlier than mid-June 2024. NZ Payroll Working patterns details

April 2024

  • AU Payroll API – We’re removing the JOBKEEPER value as an allowance type from the Payroll AU API on 1 April 2024. We’re doing this because the JobKeeper program is now defunct, and this allowance type value is no longer required. If you use this API, please ensure you no longer support creating or updating an organisation’s allowances to use the JOBKEEPER value on the POST Pay Item endpoint from 1 April 2024.

March 2024

No updates this month.

February 2024

  • Files API – We have added validation to the Associations endpoint in order to detect and reject file associations with invalid object types. If you use this API, please ensure you are using a valid object type.

January 2024

No updates this month.

December 2023

  • Accounting API – We’ve added AccountID to Invoice LineItems for the Invoices and Credit Notes endpoints of the Accounting API. This provides an identifier to track Invoices, Credit Notes and LineItems more reliably and avoid issues caused by AccountCode changes. This is a non-breaking, additive change so there is nothing you need to do, unless you’d like to make use of it. See the Invoices and Credit Notes endpoints for more information.

  • Accounting API – We’re adding 9% tax rates for Singapore to be compliant with the new GST rate. The new tax rate was made available from 6 December 2024.

  • Practice Manager API – With the recently released Reusable Contacts feature, we’ve added Add Contact, Remove Contact, and Get Contacts endpoints to the XPM Clients API. These new endpoints will allow Reusable Contacts to be added and removed via the API. See documentation for Practice Manager 3.0 and Practice Manager 3.1.

November 2023

  • Assets API – We added validation to the Assets endpoint on 15 Nov 2023. The pageSize parameter for a GET call has been restricted to an upper limit of 200 and will return a 400 bad request error if this is exceeded. This was done to better balance the load between consumers and to improve security. If you use this API and specify a pageSize limit please ensure it does not exceed 200.

October 2023

  • Accounting API – The PurchaseDetails of an item returned by the Items endpoint has changed for organisations who do not pay tax on purchases. For those organisations, when making a GET call, the TaxType field has been removed from the PurchaseDetails element. We’ve done this to better reflect business’ tax needs and ensure tax reporting is compliant with tax authorities and thus have released this quickly. If you use the Accounting API please ensure your integration is not dependent on this field. You can check the DefaultPurchaseTax property using the Organisation endpoint to identify which organisations will include the TaxType field in their responses.

  • Accounting API – We’ve added AccountID to Invoice LineItems for the Invoices and Credit Notes endpoints of the Accounting API. This provides an identifier to track Invoices, Credit Notes and LineItems more reliably and avoid issues caused by AccountCode changes. This is a non-breaking, additive change so there is nothing you need to do, unless you’d like to make use of it. See the Invoices and Credit Notes endpoints for more information.

  • Accounting API – We’ve added five new Imports and Bad Debt Recovery tax rates for Singapore to the Accounting API Tax Rates and associated accounting documents. This allows your users from Singapore to categorise their tax rates correctly to remain compliant with the tax authority’s guidelines. Please ensure your application can handle these new tax rates.

  • Accounting API – You can now delete allocations for Credit Notes, Prepayments and Overpayments via the Delete Allocations endpoint in the Accounting API. This brings the API inline with the Xero UI, and was highly requested on UserVoice. See the Credit Notes, Prepayments and Overpayments endpoints for more information.

  • Files API – We’ve recently increased an undocumented limit when retrieving associations in the Files API which prevented accessing all associations. You can now retrieve up to 100 associations for Attachments associated with an Accounting Document or Contact. To make this easier we’ve added paging and enhanced ordering. See the Associations endpoint for more information.

This page does not contain a full archive of changes to our API's.