close
Skip to main content
Image
Main content start

Changes to the API

Last updated: 10 September 2026

Xero regularly updates its APIs 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.

You can find our respective SDK release notes by following the links below.

.NET

Java

Node

Ruby

Python

PHP

Upcoming Changes

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

KiwiSaverStatus required on NZ Payroll employee tax endpoint

6 August 2026 by Xero Developer Relations

Upcoming breaking change: KiwiSaverStatus will be required when creating or updating employee tax details for all tax codes except WT and NSW. Requests to POST/payroll.xro/2.0/employees/{EmployeeID}/tax that omit KiwiSaverStatus for affected tax codes will return a 400 Bad Request. What you need to do: Update your integration to explicitly send KiwiSaverStatus for every affected tax code. If your integration already sends KiwiSaverStatus explicitly, no action is required. Xero will not provide test instances or workarounds for this change.

The target date for this change is 5 November 2026

Classic Expenses API Decommission

31 July 2025 by Xero Developer Relations

As part of efforts to decommission the Classic Expenses product we will be disabling access to the already deprecated ExpenseClaims endpoint. We will also be decommissioning the Receipts endpoint.

Depreciation Feb 2027

XPM Public API v3.0 deprecation and v3.1 focus

29 April 2026 by Xero Developer Relations

We are deprecating the Xero Practice Manager (XPM) Public API v3.0 and beginning a 12‑month migration period to retire version 3.0. To ensure long‑term scalability and align with Xero's API standards, all new investment (including JSON, field selection, and upcoming enhancements) will be focused on Practice Manager 3.1, and developers should plan to migrate their integrations to v3.1 ahead of the retirement date.

Depreciation 30th April 2027

Broad scopes deprecation

6 August 2026 by Xero Developer Relations

Broad scopes for the Accounting API are being replaced by granular scopes. Apps created on or after 2 March 2026 already use granular scopes. Existing apps have until 13 September 2027 to migrate. The accounting.transactions scope is replaced by accounting.invoices, accounting.payments, accounting.banktransactions, and accounting.manualjournals. The accounting.reports.read scope is replaced by individual report scopes. Scopes for settings, contacts, attachments, and budgets are unchanged. View full scope mapping → | FAQs →

Depreciation 13 September 2027

Change History

All updates that have been made to our APIs, including new features.

Qualifying Earnings properties on Earnings Rates and Pay Items becoming mandatory

10 September 2026 by Xero Developer Relations

The IsQualifyingEarnings property is now required in all create and update requests for AU Earnings Rates and Pay Items. Requests that omit it will return a 400 validation error.

If IsQualifyingEarnings is true: then Pay Items: IsExemptFromSuper must be false and Earnings Rates: IsSubjectToSuper must be true.

Update your integration to include IsQualifyingEarnings and ensure its value matches the relevant superannuation property.

Practice Manager 3.1 - JSON and XML response

3 September 2026 by Xero Developer Relations

Strict content negotiation for XML and JSON is now enforced in the Practice Manager 3.1 API What has changed: Previously, the API typically returned XML by default, even if your integration sent Accept: application/json. The API now strictly honors your request's Accept and Content-Type headers and returns data in the specified format.

What you need to do: If you have not already updated your integration, ensure it explicitly sets the correct Accept and Content-Type headers for the format you require (JSON or XML). Integrations that rely on receiving XML without explicitly requesting it may experience issues.

For full details please refer to the content negotiation documentation.

Overpayments webhook launched

3 September 2026 by Xero Developer Relations

Webhooks - The Prepayments webhook is now available. Subscribe to receive notifications when overpayments are created or updated in Xero. Events include the prepayment type, status, and latest update time to allow you to filter and retrieve information that is relevant to you.

Prepayments webhook launched

14 August 2026 by Xero Developer Relations

Webhooks - The Prepayments webhook is now available. Subscribe to receive notifications when prepayments are created or updated in Xero. Events include the prepayment type, status, and latest update time to allow you to filter and retrieve information that is relevant to you.

Backorders supported - Invoice

10 August 2026 by Xero Developer Relations

The Invoices endpoint now supports backorders for tracked inventory items. When an invoice exceeds available stock, retry the request with allowBackorders=true to proceed. Apps that do not support backorders can continue using their existing flow unchanged. Item responses now include QuantityOnBackorder and QuantityAvailable

Backorders are not currently supported in Canada or Singapore. See the Invoice documentation for details.

Xero Practice Manager endpoint retirement (Leads, Suppliers, Purchase Orders)

10 August 2026 by Xero Developer Relations

The Leads, Purchase Orders, and Suppliers endpoints in Xero Practice Manager have now been retired as part of the deprecation of low-usage LSPO features. Requests to these endpoints will return errors. Integrations that use them should be removed or updated.

Reference and InvoiceNumber fields for Prepayments

16 July 2026 by Xero Developer Relations

Accounting API - To evolve our API to be more internally consistent, and better reflect and align with the Xero web experience, some changes are being made to the Bank Transaction, Prepayment, and Payment endpoints.

Users will be able to retrieve references for prepayments, across all bank transaction types, and be able to use optimised filtering by reference for the BankTransaction and Prepayments endpoints.

For Bank Transaction, Prepayment, and Payment endpoints, where reference currently returns Invoice Number, e.g. for a RECEIVE-PREPAYMENT type prepayment, a new field called InvoiceNumber will be introduced. Going forward, InvoiceNumber should be treated as the source of truth for RECEIVE-PREPAYMENT numbers rather than Reference.

This will apply to both GET Prepayments and PUT Payments where detailed prepayment information is nested in the response.

UpdatedDateUTCString addition - Accounting API

16 July 2026 by Xero Developer Relations

Accounting API — We’ve added a new optional, read-only UpdatedDateUTCString field to the Payments, Prepayments, Overpayments, Credit Notes, and Invoices endpoints.

This field returns the same value as UpdatedDateUTC, but in ISO-8601 string format to make parsing easier.

This is an additive, non-breaking change, so no action is required for existing integrations. If useful, developers can begin reading UpdatedDateUTCString as an alternative to UpdatedDateUTC when consuming these responses.

New ULTRA org plan to Organisation response

30th June 2026

Accounting API: We’ve added ULTRA to the Class enum returned by the Organisation endpoint to cater for Australian organisations using the new Xero Ultra plan.

If your integration handles organisation plan types, update it to support ULTRA. Integrations that assume only existing values may fail to maintain their connection to Xero.

Authorisation updates - Accounting API

29 June 2026

Accounting API — We are aligning authorisation on several endpoints with the roles and permissions described on Xero Central. No code changes are required. However, if a connection was authorised by a user without the required permissions, affected calls will fail with an authorisation error, and that user will need their roles and permissions updated within Xero. When calling the manualjournals and journals endpoints, Standard users must have reporting permissions enabled. Connections authorised by Standard-only users will no longer be able to access these endpoints. Advisor roles are unaffected. The BankAccountAdmin permission will be required for any calls that create or update contact bank account details, whether via the Contacts endpoint or through document endpoints such as Invoices and CreditNotes. There is no change to viewing bank account details — only creating and updating are affected. You can check whether a user has the required bank account permission by calling the Organisation Actions endpoint and confirming the UpdateContactBankAccount action is ALLOWED.

Extending Payments to support creation of Amount-based FX Payments

22 June 2026 by Xero Developer Relations

Accounting API – We’ve added a new way to create multicurrency payments for ACCREC and ACCPAY documents. A multicurrency payment is created when you pay an FX document, or use an FX bank account. Currently, the FX payment would include an Amount in the currency of the document and, optionally, a CurrencyRate between the FX and organisation base currency.

Now, the payment can instead include an amount in the currency of the document (Amount), and amount paid in the currency of the account (BankAmount). Internally, we will calculate the CurrencyRate. Creating payments in this way avoids precision losses seen when dealing with large amounts and relying on CurrencyRate. It gives you full control of the amounts to match against for Bank Rec. It also avoids a common cause of accounting discrepancies: what to specify for CurrencyRate in the FX-to-same-FX payment scenario. Read more here.

Profit & Loss Reports – New 1,000 Tracking Column Limit

15 June 2026 by Xero Developer Relations

Accounting API – We introduced a hard limit of 1,000 total tracking columns for the Profit and Loss report in the Accounting API. The total number of columns is calculated by multiplying the number of tracking options within the selected tracking categories. Requests that exceed the new limit will return a 400 error. Developers do not need to change their request shape, but should handle this new failure state and guide users to reduce tracking selections where needed.

Removed the Employees endpoint documentation

5 May 2026 by Xero Developer Relations

Accounting API – The Employees endpoint documentation has been removed from the Accounting API documentation as part of the Global Pay Run (GPR) decommissioning. The endpoint was only used for managing employees in Global Pay Run, which was retired on 28 November 2025. See the Xero Central article for more information about the Global Pay Run retirement.

Decommissioned Accounting Activities API

4 May 2026 by Xero Developer Relations

Finance API - We decommissioned the Accounting Activities API. The Accounting Activities API—which included Account Usage, Lock History, Report History, and User Activities endpoints—was retired. For cash flow and financial analysis needs, we recommend using our Bank Statements API as an alternative solution. All Accounting Activities endpoints will now return errors.

Added JSON support, field selection, and Job State endpoint for Practice Manager 3.1

29 April 2026 by Xero Developer Relations

Practice Manager 3.1 - As part of the Practice Manager 3.1 release, we are:

  • Adding JSON response support alongside XML.

  • Introducing a fields query parameter for field‑level selection.

  • Adding new client fields:

    • DateOfDeath, PlaceOfBirth, ClientReferenceCode, + readonly Industry, IndustryTitle(all regions) MiddleName, Title (UK clients)

  • Releasing the Job State endpoint

These changes are backwards compatible, allow apps to fetch only the data they need, reduce payload sizes, and help manage usage‑based "data out" costs. During an initial opt‑in period, integrators can use the Xero-Features: practice-strict-content-type header to test strict content negotiation for XML/JSON before it is enforced globally.

Added CurrencyRate validation warnings

7 April 2026 by Xero Developer Relations

Accounting API - We added new CurrencyRate validation warnings to multicurrency endpoints in the Accounting API (Invoices, Credit Notes, Purchase Orders, Bank Transactions, and Payments). When a supplied CurrencyRate looks incorrect (for example, 1‑to‑1 rates where the recommended rate is not 1, inverse rates, or significantly out‑of‑range rates), the API will now return non‑blocking warnings alongside a successful response. This will help developers detect and correct suspicious FX rates in their integrations, which may stem from a misunderstanding of how multicurrency works in the API, without changing existing requests or responses.

Enabled edits to partially and fully paid AP invoices

19 March 2026 by Xero Developer Relations

Accounting API - We have relaxed the validation on the Invoices endpoint, to enable edits to non financial fields on partially and fully paid bills (AP invoices). This capability already exists in this endpoint for AR invoices, so this change is to deliver feature parity and symmetry in the API endpoint's functionality and also with the UI offering. With this change we also rolled out:

  • Reference Field Clearing: Allowing the Reference field to be cleared to an empty string instead of null for both ACCPAY and ACCREC invoices (Paid and Partially paid).

  • InvoiceNumber Field Clearing: Allowing the InvoiceNumber field to be cleared for ACCPAY invoices only (Paid and Partially paid).

Enabled paid $0 FX invoices to be edited

17 March 2026 by Xero Developer Relations

Accounting API - We have fixed a bug that prevents paid $0 FX invoices from being edited the same way paid $0 non-multicurrency invoices can be edited. This change allows parity of behaviour between actions already enabled in the invoicing UI and the API. Now FX paid $0 invoices (ACCREC & ACCPAY) can be treated the same as non-multicurrency documents of the same nature.

Added UUID field in XPM V3.0

17 March 2026 by Xero Developer Relations

Practice Manager 3.0 - We have now added the UUID field to the API V3.0 Endpoints. This UUID Field will make it easier for app partners to upgrade to V3.1.

Introduced version 2.0 support for Timesheets in AU Payroll

6 March 2026 by Xero Developer Relations

AU Payroll API - We are introducing support for AU Timesheets in the Payroll 2.0 API. Previously, timesheet support for the AU region was only available via the Payroll 1.0 API, while our NZ and UK regions utilized version 2.0. We are making this update to unify our timesheet endpoints across regions and provide a consistent developer experience within the 2.0 API. You can now choose to update your integrations to utilize the 2.0 API for AU timesheets, which is especially beneficial if your application operates across multiple regions.

Introduced webhook events for Credit Notes

4 March 2026 by Xero Developer Relations

Webhooks - Xero has made the decision to introduce a new webhook schema model, with each event type having its own schema. The very first webhook event we've introduced is for Credit Notes. There is no breaking change for existing app partners subscribed to invoices, subscription and contact events. The change will only apply to new app partners subscribing to Credit notes events, enabling them to receive near real time notifications when credit notes are created, or updated in Xero.

New granular scope for the Accounting API

4 March 2026 by Xero Developer Relations

Accounting API - You can now request smaller, more specific scopes instead of the broad accounting.transactions and accounting.reports.read scopes. This gives you more control over what your app can access, and gives your users a clearer picture of what they're approving when they connect your app. See the OAuth 2.0 scopes documentation for the full list of scopes, and the Granular scopes FAQ for more.

accounting.journals.read is no longer granted by default. To access journals, you'll need the Advanced tier and certification.

Your existing accounting.transactions and accounting.reports.read scopes will keep working for now. When you're ready, update your app to request only the scopes it needs, and ask your users to reconnect.

"Qualifying Earnings" as a new property to some AU payroll entities

18 February 2026 by Xero Developer Relations

AU Payroll API - New IsQualifyingEarnings field added to support Payday Super compliance and Qualifying Earnings classification for superannuation and ATO reporting purposes. This field is now available on:

  • Earnings Rates - Indicates whether earnings are classified as qualifying earnings for super. Must be false if IsExemptFromSuper is true. If not provided, the value will be derived from IsExemptFromSuper

  • Pay Items - Earnings Rates - Indicates whether earnings are classified as qualifying earnings for super. Must be false if IsExemptFromSuper is true. If not provided, the value will be derived from IsExemptFromSuper

  • Pay Items - Leave Types - Indicates whether a leave payment is classified as qualifying earnings for super. Must be false if SGCExempt is true. If not provided, the value will be derived from SGCExempt

  • Employees - Tax Declaration - New IncludeLeaveLoadingInQualifyingEarnings field to control if leave loading should be included when calculating qualifying earnings for super purposes.

  • Employees - Pay Template Lines - Indicates whether leave earnings on employee termination payments are classified as qualifying earnings.

For POST calls these fields are currently optional. If supplied, the value will be validated and an error returned if it fails validation. These fields will become mandatory at a future date.

NZ Payroll validation for the SalaryAndWages endpoint

28 January 2026 by Xero Developer Relations

NZ Payroll API - We introduced a new validation to the SalaryAndWages endpoint to align with the behaviour of the Xero UI. In the past we accepted daysPerWeek being "0" and numberOfUnitsPerDay having a value for a days and hours work pattern. This will no longer be accepted and numberOfUnitsPerDay must also be "0" when daysPerWeek is "0". If numberOfUnitsPerDay is not "0" when daysPerWeek is "0", we will fail with a BadRequest response (400).

Employment Status and Contract Types to UK Payroll

28 January 2026 by Xero Developer Relations

UK Payroll API - In October 2025, we communicated that new fields in the contracts collection will become mandatory for creating a new employee or adding employment details to an active employee. This change was due to take place on Jan 20, 2026. This will now remain optional moving forward. Whilst it will remain optional, we recommend supplying this data as part of the employee creation process as it will ensure completeness and reduce call to actions on the UI to update these employee records.

Accounts can no longer be deleted if they have a payment service attached

16 December 2025 by Xero Developer Relations

Accounting API - Account DELETE requests for accounts which are linked to a payment service will now fail with a BadRequest response (400). The Account DELETE failed message will change to 'Account cannot be deleted as there is an approved transaction, fixed asset or payment service assigned to it'.

Validation for ACCPAY and ACCPAYCREDITNOTE documents is being relaxed

8 December 2025 by Xero Developer Relations

Accounting API - Validation for ACCPAY and ACCPAYCREDITNOTE documents is being relaxed. Documents with only CIS Materials Purchase Lines can be saved in any status (DRAFT, SUBMITTED, AUTHORISED) regardless of whether the contact has a CIS deduction rate. Documents with at least one CIS Labour Expense Line can be saved as DRAFT or SUBMITTED without a CIS deduction rate, but AUTHORISED status still requires one.

XPM Client notes migration from Folders to Tags

8 December 2025 by Xero Developer Relations

Practice Manager 3.0 & 3.1 – 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. 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, US, CA, and ROW XPM accounts. These changes will apply to practices as they transition to the Single Client

IRS changes for 2025 report is now available

12 November 2025 by Xero Developer Relations

Accounting API - IRS changes for 2025 report is now available for the Ten Ninety Nine Report. This is a non-breaking change. Excess golden parachute payments should be reported in NEC forms (previously in MISC forms). Set up your rules in Xero for 2025 report year to reflect the new changes.

Payroll AU API PayRuns Endpoint Update

10 November 2025 by Xero Developer Relations

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.

NZ Payroll Updates to comply with the Holidays Act

10 November 2025 by Xero Developer Relations

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 POST & DELETE. Salary & Wages locking behaviour. 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 POST Employment. Currently pay frequencies can be assigned to employees, but after the employee’s leave units have been converted, a pay frequency with an end date prior to their date of conversion can not be used.

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 POST pay runs.

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 POST & PUT employee 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.

Introducing Employment Status and Contract Types to UK Payroll

14 October 2025 by Xero Developer Relations

UK Payroll API - To help support our UK customers with capturing Employment Status information, we’ve added new functionality to allow API consumers to specify an employee's employment status (i.e. Employee, Worker) and their contract type (i.e. Full Time, Part Time, Zero Hour). 'Unspecified' is a system generated value that is used to represent any gaps between the start date of an employee and their first contract. All new fields will initially be optional. They will become mandatory (breaking) from 20th Jan 2026 when creating a new employee or adding employment details to an active employee. As part of this change we’re also locking down the ability to change Employment Start Date once an employee has been included in a pay run.

Update to Contacts API to mask US Tax Numbers

22 September 2025 by Xero Developer Relations

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

New Document Type validation for Payments

6 September 2025 by Xero Developer Relations

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.

New properties to Batch Payments

27 May 2025 by Xero Developer Relations

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)

Update to DiscountAmount and DiscountRate values

25 May 2025 by Xero Developer Relations

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.

New SIMPLE org plan to Organisation response

1 May 2025 by Xero Developer Relations

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

New neonatalcare leave earnings types

7 April 2025 by Xero Developer Relations

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.

New fields for the National Insurance category data type

4 March 2025 by Xero Developer Relations

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

Removing some fields from the CashValidation API

10 February 2025 by Xero Developer Relations

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

New Validation for Tracking Categories

10 February 2025 by Xero Developer Relations

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.

New Validation for AU Payroll Employees endpoint

10 February 2025 by Xero Developer Relations

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.

New XPM Endpoint to support pagination in the Client list

5 February 2025 by Xero Developer Relations

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.

2023-2024 Changes

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