Xero's most commonly viewed reports (listed below) can be retrieved using the Xero API. These reports typically contain a summary of data that may be useful for your own application. e.g. it may be more easier and more efficient to use a Report endpoint to fetch data rather than retrieve individual invoices and total these yourself.
Each report has its own endpoint e.g. https://api.xero.com/api.xro/2.0/Reports/[Report Name] and can be returned in either XML (default) or JSON format.
An application that has been authorised by a Standard user with the "No reports" role will not be able to access the Reports or Journals endpoints (A HTTP 403 error will be returned in this case).
Each report has different optional parameters. The report parameters should be added as a separate query strings. For
example:
GET https://api.xero.com/api.xro/2.0/Reports/AgedReceivablesByContact?fromDate=2010-01-01&toDate=2011-01-01
The layout of each report is a collection of rows and cells. Rows can be of various types (e.g. header, section, row and summary row elements). Cells can contain values and attributes with nested values.
Try the API Previewer to get familiar with the response format for each report or see the Trial Balance example below.
More details about each reporting endpoint are listed below. To learn more about the composition of specific reports refer to the Report Centre.
| 1099 Report (US organisations only) |
| Aged Payables By Contact |
| Aged Receivables By Contact |
| Balance Sheet |
| Bank Summary |
| BAS Report (Australia organisations only) |
| Budget Summary |
| Executive Summary |
| GST Report (New Zealand organisations only) |
| Profit And Loss |
| Trial Balance |
| URL | https://api.xero.com/api.xro/2.0/Reports/TenNinetyNine |
| Methods Supported | GET |
| Description | Returns the 1099 report, for all years, as configured by the rules in the Xero app. There have been some changes in the 1099 report, introduced by the IRS, in effect from tax year 2020. In essence, the regulation change is to remove box number 7 (non employee compensation) from the 1099-MISC and put this into a new form called the 1099-NEC form. Both 1099-MISC and 1099-NEC will be included in report years 2020 and later. This change is reflected in the reponse from the Xero API, for year 2020. All responses returned by the API for the year 2019 and before will remain the same. Please refer to the examples on the right for the modified contract. |
| reportYear | Year of the report e.g. 2020 |
Example response for GET TenNinetyNine (2019 and before)
GET https://api.xero.com/api.xro/2.0/Reports/TenNinetyNine?reportYear=2019
Example response for GET TenNinetyNine (2020 and after)
GET https://api.xero.com/api.xro/2.0/Reports/TenNinetyNine?reportYear=2020
| URL | https://api.xero.com/api.xro/2.0/Reports/AgedPayablesByContact |
| Methods Supported | GET |
| Description | Returns aged payables up to the end of the current month by default |
| contactID | Contact ID e.g. 5040915e-8ce7-4177-8d08-fde416232f18 |
| date | Shows payments up to this date e.g. 2014-04-30. Defaults to end of the current month |
| fromDate | Show all payable invoices from this date for contact |
| toDate | Show all payable invoices to this date for the contact |
Example response for GET AgedPayablesByContact
GET https://api.xero.com/api.xro/2.0/Reports/AgedPayablesByContact?ContactID=5040915e-8ce7-4177-8d08-fde416232f18
| URL | https://api.xero.com/api.xro/2.0/Reports/AgedReceivablesByContact |
| Methods Supported | GET |
| Description | Returns aged receivables up to the end of the current month by default |
| contactID | Contact ID e.g. 5040915e-8ce7-4177-8d08-fde416232f18 |
| date | Shows payments up to this date e.g. 2014-04-30. Defaults to end of the current month |
| fromDate | Show all receivable invoices from this date for contact |
| toDate | Show all receivable invoices to this date for the contact |
| URL | https://api.xero.com/api.xro/2.0/Reports/BalanceSheet |
| Methods Supported | GET |
| Description | Returns a balance sheet for the end of the month of the specified date. YTD values are shown too. |
| date | e.g. 2014-04-30 |
| periods | The number of periods to compare (integer between 1 and 11) |
| timeframe | The period size to compare to (MONTH, QUARTER, YEAR) |
| trackingOptionID1 | The balance sheet will be filtered by this option if supplied. Note you cannot filter just by the TrackingCategory. |
| trackingOptionID2 | If you want to filter by more than one tracking category option then you can specify a second option too. See the Balance Sheet report in Xero learn more about this behavior when filtering by tracking category options |
| standardLayout | If you set this parameter to "true" then no custom report layouts will be applied to response |
| paymentsOnly | Set this to true to get cash transactions only |
Example response for GET BalanceSheet
GET https://api.xero.com/api.xro/2.0/Reports/BalanceSheet
| URL | https://api.xero.com/api.xro/2.0/Reports/BankSummary |
| Methods Supported | GET |
| Description | Returns the balances and cash movements for each bank account |
| fromDate | e.g. 2014-03-01 |
| toDate | e.g. 2014-03-31 |
| URL | https://api.xero.com/api.xro/2.0/Reports |
| Methods Supported | GET |
| Description | Returns a list of published BAS reports. NB This works for Australia based organisations only |
| ReportID | Add the ReportID to the end of the url to retrieve the details of a specific BAS Report |
Example response for an individual published BAS Report
GET https://api.xero.com/api.xro/2.0/Reports/3d0a1240-e606-4fae-a823-77bcf79d5e79
| URL | https://api.xero.com/api.xro/2.0/Reports/BudgetSummary |
| Methods Supported | GET |
| Description | Returns a summary of your monthly budget |
| date | e.g. 2014-04-30 |
| periods | The number of periods to compare (integer between 1 and 12) |
| timeframe | The period size to compare to (1=month, 3=quarter, 12=year) |
| URL | https://api.xero.com/api.xro/2.0/Reports/ExecutiveSummary |
| Methods Supported | GET |
| Description | A summary including monthly totals and some common business ratios |
| date | e.g. 2014-03-31 |
| URL | https://api.xero.com/api.xro/2.0/Reports |
| Methods Supported | GET |
| Description | Returns a list of finalised GST reports. NB This currently works for New Zealand based organisations only. Published GST Reports before 11 Nov 2013 will also be returned |
| ReportID | Add the ReportID to the end of the url to retrieve the details of a published GST Report |
Example response for an individual published GST Report
GET https://api.xero.com/api.xro/2.0/Reports/2be4a28b-467a-4bd1-baf8-8d6622a5b930
| URL | https://api.xero.com/api.xro/2.0/Reports/ProfitAndLoss |
| Methods Supported | GET |
| Description | Returns a profit and loss for the current month by default. An alternate date range can also be specified using the optional parameters listed below. |
| fromDate | e.g. 2014-03-01 |
| toDate | e.g. 2014-03-31 |
| periods | The number of periods to compare (integer between 1 and 11) |
| timeframe | The period size to compare to (MONTH, QUARTER, YEAR) |
| trackingCategoryID | If you specify the trackingCategoryID parameter then the Profit and Loss Report will show figures for each of the options in the category as separate columns. See the Profit and Loss Report in Xero to learn more about this behavior when filtering by a tracking category. |
| trackingOptionID | if you specify this parameter in addition to the trackingCategoryID then just one option will be returned (i.e. 1 column only) |
| trackingCategoryID2 | If you specify a second trackingCategoryID parameter then the Profit and Loss Report will show figures for each combination of options from the two categories as separate columns. See the Profit and Loss Report in Xero to learn more about this behaviour when filtering by two tracking categories. |
| trackingOptionID2 | if you specify this parameter in addition to a second trackingCategoryID then just one option will be returned combined with the option/s from the first tracking category |
| standardLayout | If you set this parameter to "true" then no custom report layouts will be applied to response |
| paymentsOnly | Set this to true to get cash transactions only |
For organisations in most regions, the standard layout of the profit and loss report will group multi currency system accounts into a single line with a Value of FXGROUPID (instead of an AccountID).
This is not the case for US organisations and Australian demo companies. Multi-currency system accounts will be displayed seperately with their respective AccountIDs.
Example response from GET ProfitAndLoss
GET https://api.xero.com/api.xro/2.0/Reports/ProfitAndLoss?fromDate=2017-02-01&toDate=2017-02-28
| URL | https://api.xero.com/api.xro/2.0/Reports/TrialBalance |
| Methods Supported | GET |
| Description | Returns a trial balance for the current month up to the date specified. YTD values are shown too. |
| date | As at date e.g. 2014-10-31 |
| paymentsOnly | Set this to true to get cash transactions only |
Example response for GET TrialBalance
GET https://api.xero.com/api.xro/2.0/Reports/TrialBalance