Xero Reports

Xero Financial Reports

Overview

Xero exposes its financial reports through the API as structured, programmatically parseable data. For MSPs, these reports drive profitability tracking by service line, client payment-behavior monitoring, cash flow management, and financial statements for stakeholders.

Anti-triggers

• Individual transactions rather than aggregates — reports return summarized rows with no drill-through; the underlying records are xero-invoices and xero-payments.
• The GL structure a report groups by — use xero-accounts.
• The same reports in QuickBooks — use qbo-reports.

Core Concepts

Available Reports

Report Response Structure

All Xero reports share one nested Rows/Cells shape. Values arrive as strings and must be parsed to numbers:

{
  "Reports": [
    {
      "ReportID": "ProfitAndLoss",
      "ReportName": "Profit and Loss",
      "ReportType": "ProfitAndLoss",
      "ReportDate": "23 February 2026",
      "UpdatedDateUTC": "/Date(1772006400000)/",
      "Rows": [
        {
          "RowType": "Header",
          "Cells": [
            { "Value": "" },
            { "Value": "1 Mar 2026 to 31 Mar 2026" }
          ]
        },
        {
          "RowType": "Section",
          "Title": "Revenue",
          "Rows": [
            {
              "RowType": "Row",
              "Cells": [
                { "Value": "Managed Services Revenue", "Attributes": [{ "Value": "acc-id-200" }] },
                { "Value": "45000.00", "Attributes": [{ "Value": "acc-id-200" }] }
              ]
            }
          ]
        },
        {
          "RowType": "SummaryRow",
          "Cells": [
            { "Value": "Total Revenue" },
            { "Value": "67500.00" }
          ]
        }
      ]
    }
  ]
}

Row Types

API Patterns

Reports are GET-only and take their parameters in the query string. Period reports (P&L, Bank Summary) use fromDate/toDate; point-in-time reports (Balance Sheet, Aged Receivables/Payables, Trial Balance) use a single date. All dates are YYYY-MM-DD.

curl -s -X GET "https://api.xero.com/api.xro/2.0/Reports/ProfitAndLoss?fromDate=2026-03-01&toDate=2026-03-31" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "xero-tenant-id: ${XERO_TENANT_ID}" \
  -H "Accept: application/json"

Parameters worth knowing across reports:

See references/api.md for the full request catalog, per-report parameter tables, and the complete endpoint reference.

Common Workflows

MSP Monthly Financial Review

Fetch P&L, Balance Sheet, Aged Receivables, and Aged Payables for the closing month in parallel, then parse each into a summary. Reports are independent requests, so parallelizing is safe and materially faster.

Revenue and Margin Analysis

Walk the P&L Rows tree, matching Section titles (Revenue/Income, Less Cost of Sales/Direct Costs) and reading the SummaryRow totals. Section titles vary by chart-of-accounts layout — match on more than one candidate title.

Overdue Client Review

Parse the Aged Receivables sections into per-contact aging buckets (current, 30, 60, 90, older) and sort by total overdue. Cells are positional, so index by column order rather than by name.

Year-over-Year Comparison

Request the same P&L period for the current and prior year, then compare parsed revenue totals.

See references/examples.md for working JavaScript implementations of each workflow.

Error Handling

Common API Errors

Report Parsing Errors

Gotchas

• Reports are expensive - Cache results keyed on the report name plus its parameters; repeated identical requests burn rate limit for identical data.
• Always specify dates explicitly - Omitting fromDate/toDate or date yields Xero's default period, which is rarely the one you meant.
• Parse defensively - Cells can be absent or empty strings; coerce to 0 rather than assuming a numeric value.
• Tracking categories are the MSP lever - Filtering P&L by tracking category is the only way to get per-service-line profitability out of the standard reports.
• Cash vs accrual changes the answer - paymentsOnly=true reports cash movements only; use it for cash flow analysis, not for revenue recognition.

Related Skills

• Xero Invoices - Invoice data feeding reports
• Xero Payments - Payment data in reports
• Xero Accounts - Account structure for P&L and Balance Sheet
• Xero Contacts - Contact-level report filtering
• Xero API Patterns - API reference