Reports


Overview

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.

Endpoints

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.

Permissions

An application that has been authorised by a Standard user with the “No reports” role will not be able to access the Reports endpoint (A HTTP 401 error will be returned in this case).

Parameters

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

Layout

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 Statement
Bank Summary
BAS Report (Australia organisations only)
Budget Summary
Executive Summary
GST Report (New Zealand organisations only)
Profit And Loss
Trial Balance

1099 Report

URL https://api.xero.com/api.xro/2.0/Reports/TenNinetyNine
Methods Supported GET
Description Returns the 1099 report as configured by the rules in the Xero app

Optional parameters for GET 1099

reportYear Year of the report e.g. 2013

Aged Payables By Contact

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

Required parameters for GET AgedPayablesByContact

contactID Contact ID e.g. 5040915e-8ce7-4177-8d08-fde416232f18

Optional parameters for GET AgedPayablesByContact

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

Aged Receivables By Contact

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

Required parameters for GET AgedReceivablesByContact

contactID Contact ID e.g. 5040915e-8ce7-4177-8d08-fde416232f18

Optional parameters for GET AgedReceivablesByContact

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

Balance Sheet

URL https://api.xero.com/api.xro/2.0/Reports/BalanceSheet
Methods Supported GET
Description Returns a balance sheet for the current month up to the date specified. YTD values are shown too.

Optional parameters for GET BalanceSheet

date e.g. 2014-04-30
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

Bank Statement

URL https://api.xero.com/api.xro/2.0/Reports/BankStatement
Methods Supported GET
Description Returns the statement lines for a specified bank account

Required parameters for GET BankStatement

bankAccountID bankAccountID e.g. 5040915e-8ce7-4177-8d08-fde416232f18

Optional parameters for GET BankStatement

fromDate e.g. 2012-03-01
toDate e.g. 2012-04-30

Example response for GET BankStatement

<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Id>fbb67acb-01ce-436c-ad94-c3f2296228b2</Id>
  <Status>OK</Status>
  <ProviderName>Xero API Previewer</ProviderName>
  <DateTimeUTC>2013-08-20T03:39:39.5658282Z</DateTimeUTC>
  <Reports>
    <Report>
      <ReportID>BankStatement</ReportID>
      <ReportName>Bank Statement</ReportName>
      <ReportType>BankStatement</ReportType>
      <ReportTitles>
        <ReportTitle>Bank Statement</ReportTitle>
        <ReportTitle>Business Bank Account</ReportTitle>
        <ReportTitle>Demo Company (AU)</ReportTitle>
        <ReportTitle>From 1 August 2013 to 20 August 2013</ReportTitle>
      </ReportTitles>
      <ReportDate>20 August 2013</ReportDate>
      <UpdatedDateUTC>2013-08-20T03:39:39.5658282Z</UpdatedDateUTC>
      <Rows>
        <Row>
          <RowType>Header</RowType>
          <Cells>
            <Cell>
              <Value>Date</Value>
            </Cell>
            <Cell>
              <Value>Description</Value>
            </Cell>
            <Cell>
              <Value>Reference</Value>
            </Cell>
            <Cell>
              <Value>Reconciled</Value>
            </Cell>
            <Cell>
              <Value>Source</Value>
            </Cell>
            <Cell>
              <Value>Amount</Value>
            </Cell>
            <Cell>
              <Value>Balance</Value>
            </Cell>
          </Cells>
        </Row>
        <Row>
          <RowType>Section</RowType>
          <Rows>
            <Row>
              <RowType>Row</RowType>
              <Cells>
                <Cell>
                  <Value>2013-08-01T00:00:00</Value>
                </Cell>
                <Cell>
                  <Value>Opening Balance</Value>
                </Cell>
                <Cell />
                <Cell />
                <Cell />
                <Cell />
                <Cell>
                  <Value>-1792.15</Value>
                </Cell>
              </Cells>
            </Row>
            <Row>
              <RowType>Row</RowType>
              <Cells>
                <Cell>
                  <Value>2013-08-04T00:00:00</Value>
                </Cell>
                <Cell>
                  <Value>Melbourne Mags</Value>
                </Cell>
                <Cell>
                  <Value>Eft  </Value>
                </Cell>
                <Cell>
                  <Value>Yes</Value>
                </Cell>
                <Cell>
                  <Value>Import</Value>
                </Cell>
                <Cell>
                  <Value>-21.90</Value>
                </Cell>
                <Cell>
                  <Value>-1814.05</Value>
                </Cell>
              </Cells>
            </Row>
            <Row>
              <RowType>Row</RowType>
              <Cells>
                <Cell>
                  <Value>2013-08-04T00:00:00</Value>
                </Cell>
                <Cell>
                  <Value>MCO Cleaning</Value>
                </Cell>
                <Cell />
                <Cell>
                  <Value>Yes</Value>
                </Cell>
                <Cell>
                  <Value>Import</Value>
                </Cell>
                <Cell>
                  <Value>-170.50</Value>
                </Cell>
                <Cell>
                  <Value>-1984.55</Value>
                </Cell>
              </Cells>
            </Row>
          </Rows>
        </Row>
      </Rows>
     ....
    </Report>
  </Reports>
</Response>

Bank Summary

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

Optional parameters for GET BankSummary

fromDate e.g. 2014-03-01
toDate e.g. 2014-03-31

BAS Report

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

You can retrieve an individual published BAS Report by specifying the identifier of the report e.g. https://api.xero.com/api.xro/2.0/Reports/2BE4A28B-467A-4BD1-BAF8-8D6622A5B930

<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Id>435ff851-3700-458f-b5ce-365a0eda7b4d</Id>
  <Status>OK</Status>
  <ProviderName>Xero API Previewer</ProviderName>
  <DateTimeUTC>2011-02-21T00:36:14.3339709Z</DateTimeUTC>
  <Reports>
<Report>
    <ReportID>3d0a1240-e606-4fae-a823-77bcf79d5e79</ReportID>
    <ReportName>Activity Statement</ReportName>
    <ReportType>SalesTaxReturn</ReportType>
    <ReportDate>1 Nov 2011 to 30 Nov 2011</ReportDate>
    <UpdatedDateUTC>2011-12-18T19:59:27.84</UpdatedDateUTC>
    <Attributes>
      <ReportAttribute>
        <Name>fromDate</Name>
        <Description>From</Description>
        <Value>2011-11-01T00:00:00</Value>
      </ReportAttribute>
      <ReportAttribute>
        <Name>dateTo</Name>
        <Description>To</Description>
        <Value>2011-11-30T00:00:00</Value>
      </ReportAttribute>
    </Attributes>
    <Fields>
      <ReportField>
        <FieldID>ABN</FieldID>
        <Description>ABN</Description>
        <Value>53003086616</Value>
      </ReportField>
      <ReportField>
        <FieldID>GSTBasis</FieldID>
        <Description>GST Accounting Method</Description>
        <Value>Accruals Basis</Value>
      </ReportField>
      <ReportField>
        <FieldID>W1</FieldID>
        <Description>Total salary, wages and other payments</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>W2</FieldID>
        <Description>Amount withheld from payments shown at W1</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>W4</FieldID>
        <Description>Amount withheld where no ABN is quoted</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>W3</FieldID>
        <Description>Other amounts withheld (excluding any amount shown in W2 or W4)</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>W5</FieldID>
        <Description>Total amounts withheld (W2 + W4 + W3)</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>4</FieldID>
        <Description>PAYG tax withheld</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>7</FieldID>
        <Description>Deferred company/fund instalment</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>8A</FieldID>
        <Description>4+7</Description>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>8B</FieldID>
        <Value>0</Value>
      </ReportField>
      <ReportField>
        <FieldID>9</FieldID>
        <Description>Your refund</Description>
        <Value>0</Value>
      </ReportField>
    </Fields>
  </Report>

  </Reports>
</Response>

Budget Summary

URL https://api.xero.com/api.xro/2.0/Reports/BudgetSummary
Methods Supported GET
Description Returns a summary of your monthly budget

Optional parameters for GET BudgetSummary

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)

Executive Summary

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

Optional parameters for GET ExecutiveSummary

date e.g. 2014-03-31

GST Report

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

You can retrieve an individual published GST Report by specifying the identifier of the report e.g. https://api.xero.com/api.xro/2.0/Reports/2BE4A28B-467A-4BD1-BAF8-8D6622A5B930

<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Id>435ff851-3700-458f-b5ce-365a0eda7b4d</Id>
  <Status>OK</Status>
  <ProviderName>Xero API Previewer</ProviderName>
  <DateTimeUTC>2011-02-21T00:36:14.3339709Z</DateTimeUTC>
  <Reports>
    <Report>
      <ReportID>2be4a28b-467a-4bd1-baf8-8d6622a5b930</ReportID>
      <ReportName>GST and Provisional Tax Return</ReportName>
      <ReportType>OtherReport</ReportType>
      <ReportDate>1 Dec 2010 to 31 Jan 2011</ReportDate>
      <UpdatedDateUTC>2011-02-02T03:49:10.397</UpdatedDateUTC>
      <Fields>
        <ReportField>
          <FieldID>1</FieldID>
          <Description>Registration number</Description>
          <Value>98-765-043</Value>
        </ReportField>
        <ReportField>
          <FieldID>GSTBasis</FieldID>
          <Description>GST basis</Description>
          <Value>Invoice Basis</Value>
        </ReportField>
        <ReportField>
          <FieldID>PeriodCovered</FieldID>
          <Description>Period covered by the return</Description>
          <Value>2 Monthly</Value>
        </ReportField>
        <ReportField>
          <FieldID>From</FieldID>
          <Description>From</Description>
          <Value>2010-12-01T00:00:00</Value>
        </ReportField>
        <ReportField>
          <FieldID>2</FieldID>
          <Description>To</Description>
          <Value>2011-01-31T00:00:00</Value>
        </ReportField>
        <ReportField>
          <FieldID>5</FieldID>
          <Description>Total sales and income for the period (including GST and zero-rated Supplies)</Description>
          <Value>115.00</Value>
        </ReportField>
       
      ...

      </Fields>
    </Report>
  </Reports>
</Response>

Profit And Loss

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.

Optional parameters for GET ProfitAndLoss

fromDate e.g. 2014-03-01
toDate e.g. 2014-03-31
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)
standardLayout If you set this parameter to “true” then no custom report layouts will be applied to response

Example Url

GET /api.xro/2.0/Reports/ProfitAndLoss?fromDate=2014-09-30&toDate=2014-10-31

Trial Balance

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.

Optional parameters for GET TrialBalance

date As at date e.g. 2014-10-31
paymentsOnly Set this to true to get cash transactions only

Example response for GET TrialBalance

<Response xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Id>db04a7a3-5543-4fbe-909f-0482182828c3</Id>
  <Status>OK</Status>
  <ProviderName>Xero API Previewer</ProviderName>
  <DateTimeUTC>2011-02-20T21:50:43.6129168Z</DateTimeUTC>
  <Reports>
    <Report>
      <ReportID>TrialBalance</ReportID>
      <ReportName>Trial Balance</ReportName>
      <ReportType>TrialBalance</ReportType>
      <ReportTitles>
        <ReportTitle>Trial Balance</ReportTitle>
        <ReportTitle>Demo Company (NZ)</ReportTitle>
        <ReportTitle>As at 30 August 2010</ReportTitle>
      </ReportTitles>
      <ReportDate>21 February 2011</ReportDate>
      <UpdatedDateUTC>2011-02-20T21:50:43.6129168Z</UpdatedDateUTC>
      <Rows>
        <Row>
          <RowType>Header</RowType>
          <Cells>
            <Cell>
              <Value>Account</Value>
            </Cell>
            <Cell>
              <Value>Debit</Value>
            </Cell>
            <Cell>
              <Value>Credit</Value>
            </Cell>
            <Cell>
              <Value>YTD Debit</Value>
            </Cell>
            <Cell>
              <Value>YTD Credit</Value>
            </Cell>
          </Cells>
        </Row>
        <Row>
          <RowType>Section</RowType>
          <Title>Revenue</Title>
          <Rows>
            <Row>
              <RowType>Row</RowType>
              <Cells>
                <Cell>
                  <Value>Interest Income (270)</Value>
                  <Attributes>
                    <Attribute>
                      <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Attributes>
                    <Attribute>
                      <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Value>0.00</Value>
                  <Attributes>
                    <Attribute>
                      <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Attributes>
                    <Attribute>
                      <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Value>500.00</Value>
                  <Attributes>
                    <Attribute>
                      <Value>e9482110-7245-4a76-bfe2-14500495a076</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
              </Cells>
            </Row>
            <Row>
              <RowType>Row</RowType>
              <Cells>
                <Cell>
                  <Value>Sales (200)</Value>
                  <Attributes>
                    <Attribute>
                      <Value>5040915e-8ce7-4177-8d08-fde416232f18</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Attributes>
                    <Attribute>
                      <Value>5040915e-8ce7-4177-8d08-fde416232f18</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Value>12180.25</Value>
                  <Attributes>
                    <Attribute>
                      <Value>5040915e-8ce7-4177-8d08-fde416232f18</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Attributes>
                    <Attribute>
                      <Value>5040915e-8ce7-4177-8d08-fde416232f18</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
                <Cell>
                  <Value>20775.53</Value>
                  <Attributes>
                    <Attribute>
                      <Value>5040915e-8ce7-4177-8d08-fde416232f18</Value>
                      <Id>account</Id>
                    </Attribute>
                  </Attributes>
                </Cell>
              </Cells>
            </Row>
          </Rows>
        </Row>
        
        ..... 

        <Row>
          <RowType>Section</RowType>
          <Rows>
            <Row>
              <RowType>SummaryRow</RowType>
              <Cells>
                <Cell>
                  <Value>Total</Value>
                </Cell>
                <Cell>
                  <Value>17447.02</Value>
                </Cell>
                <Cell>
                  <Value>17447.02</Value>
                </Cell>
                <Cell>
                  <Value>33459.76</Value>
                </Cell>
                <Cell>
                  <Value>33459.76</Value>
                </Cell>
              </Cells>
            </Row>
          </Rows>
        </Row>
      </Rows>
    </Report>
  </Reports>
</Response>