QuickBooks Online Reports

QuickBooks Online Reports

Overview

QuickBooks Online provides a comprehensive set of financial reports accessible via the API. For MSPs, the most critical reports are Accounts Receivable Aging (tracking which clients owe money and how overdue), Profit & Loss (measuring overall and per-client profitability), Balance Sheet (financial position), and Accounts Payable Aging (tracking vendor obligations). Reports are read-only API calls that return structured data suitable for dashboards, alerts, and automated analysis.

Anti-triggers

• A specific transaction — reports are aggregates with their own nested row structure and their own rounding. Pulling one invoice, payment, or bill out of a report is the wrong path; use qbo-invoices, qbo-payments, or qbo-expenses.
• The books are in Xero, not QuickBooks — use xero-reports. Both produce "P&L" and "aged receivables" under those exact names.
• Margin on resold cloud licences — the cost side sits with the distributor and the revenue side in QBO; reconciling them is shared-skills-billing-reconciliation, not a single report.
• Service-delivery metrics — ticket volume, SLA attainment, and utilisation are PSA reporting, not accounting; use the PSA's skills.

Key Concepts

Report Categories

All reports are served from /v3/company/{realmId}/reports/{ReportName}. See references/api.md for the complete endpoint catalog with per-report request examples.

Report Parameters

All reports support common parameters for filtering and customization:

Date Macros

Report Response Structure

All reports return a common structure:

{
  "Header": {
    "ReportName": "ProfitAndLoss",
    "DateMacro": "Last Month",
    "StartPeriod": "2026-01-01",
    "EndPeriod": "2026-01-31",
    "Currency": "USD",
    "Option": [
      { "Name": "AccountingMethod", "Value": "Accrual" }
    ]
  },
  "Columns": {
    "Column": [
      { "ColTitle": "", "ColType": "Account" },
      { "ColTitle": "Total", "ColType": "Money" }
    ]
  },
  "Rows": {
    "Row": [...]
  }
}

A/R Aging Buckets

Parsing Report Data

Rows.Row is a recursive tree, not a flat list. A row is either a type: "Section" node — carrying Header.ColData (the section label), a nested Rows.Row array, and a Summary.ColData totals row — or a leaf data row carrying only ColData. Any parser must recurse into Rows.Row and handle both shapes; the totals you usually want live on Summary, not on the child data rows.

See references/examples.md for the nested row JSON and a recursive parser implementation.

Common Workflows

MSP Monthly Financial Review

Fetch ProfitAndLoss, AgedReceivables, AgedPayables, and CustomerSales concurrently for the target month, then parse each into a single summary object.

Client Profitability Dashboard

Run ProfitAndLoss with summarize_column_by=Customers. Each customer becomes a column; read Columns.Column[].ColTitle for client names and pull the Income, Expenses, and Net Income section summaries.

A/R Aging Collections Alert

Run AgedReceivableDetail with date_macro=Today, walk the customer sections, and flag invoices past a days-overdue and amount threshold.

Monthly Revenue Trend

Run ProfitAndLoss over a multi-month range with summarize_column_by=Month, then read the Income section summary across columns.

Cash Flow Snapshot

Fetch AgedReceivables, AgedPayables, and BalanceSheet concurrently to combine receivable inflows, payable obligations, and current cash position.

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

Error Handling

Common API Errors

Validation Errors

See references/examples.md for a retry-and-refresh error recovery wrapper.

Best Practices

1. Use date macros - Prefer date_macro for standard periods (less error-prone than manual dates)
2. Specify accounting method - Always set accounting_method explicitly; the company default otherwise decides whether Accrual or Cash numbers come back
3. Summarize by column - Use summarize_column_by=Month for trend analysis
4. Cache reports - Reports are read-only; cache results for dashboards
5. Filter by customer - Use the customer parameter for client-specific reports
6. Parse recursively - Report rows are nested; use recursive parsing
7. Include minor version - Always add minorversion=73 for latest report features
8. Run reports in parallel - Fetch multiple reports concurrently for dashboards
9. Monitor A/R aging - Set up automated alerts for overdue accounts

Related Skills

• QBO Customers - Customer data for report filtering
• QBO Invoices - Invoice data behind A/R aging
• QBO Payments - Payment data behind cash flow
• QBO Expenses - Expense data behind P&L
• QBO API Patterns - API reference