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