Data Sources

Metric-to-connector mapping. Pull everything in one parallel batch; never serially.

The ledger — the spine of most reports

Most SMB reports resolve to the accounting ledger. Whichever is connected — MYOB, NetSuite, QuickBooks, Xero, or Zoho Books — is the source; they are peers (../../../shared/connector-neutrality.md). The metric families below are written against QuickBooks report names; the NetSuite, Xero, MYOB, and Zoho Books sections say where each family comes from there. Amounts carry the business's currency code (../../../shared/currency-and-locale.md).

QuickBooks

Fallback: if QuickBooks returns empty, a sync-in-progress state, or an auth error, mark the affected metrics "n/a — QuickBooks unavailable" and continue with other sources. Do not retry in a loop and do not ask the owner to reconnect mid-report.

Aging reports must be constrained, every time

An unconstrained aging call fails on any real book. On a mid-size ledger the AR aging summary returns well over a hundred thousand characters, overflows the tool output limit, and comes back as nothing usable. This is not an edge case; it is the normal result for a business with a few hundred customers.

Always pass narrowing arguments. The three that matter:

• a top-N cap, so only the biggest balances come back
• a minimum days-overdue threshold, which drops the current bucket entirely
• a minimum dollar threshold, which drops the long tail of small balances

For a report, "the twenty largest balances at least one day overdue" is the useful shape and it always fits. If the owner genuinely needs every line, pull the detail report per customer rather than asking for the whole book at once.

The same rule applies to AP aging, which comes from the detail report: narrow it by vendor or due date. It is the smaller report of the two, but it grows the same way.

Sales by customer double-counts parent customers

The sales-by-customer summary returns two rows for any customer with sub-customers or jobs underneath it: a summary row for the parent, and a separate total row for the same parent. They carry the same figure. The report's own top-customer list contains both.

Read naively, this puts a customer in your rankings twice — once under its own name and once as "Total for" that name — and overstates every concentration figure you compute from it.

Drop rows whose metadata type marks them as a total before you rank, sum, or compute concentration. Keep the parent summary row; it is the real one. Concentration built on unfiltered rows is wrong every time, not occasionally.

HubSpot — pipeline and customers

Watch out: CRM deal values are forecasts. When a report mixes CRM and accounting data, revenue always comes from the books. Say which source each number came from.

Payment processors

Double-count risk. A Shopify order settled through Stripe appears in both. Pick one system as the revenue source per report, state the choice in the summary, and use the other only for fees and timing.

Shopify

Orders, SKU-level revenue, variant performance, fulfillment status, refunds. Best source for anything grouped by product.

COGS usually is not in Shopify. Margin metrics need QuickBooks or an uploaded cost file.

NetSuite

Common at the larger end of the segment. Same metric families as the QuickBooks section via ns_runReport and ns_runCustomSuiteQL, plus item-level COGS and inventory valuation.

Xero

Same metric families as the QuickBooks section, from get_profit_and_loss (revenue, expenses, net income, by period), get_aged_receivables (AR aging, same aging-constraint rules), and get_bills (AP). The organisation record supplies the base currency and financial year, so period references resolve against the business's year end.

Ramp and Expensify

Card spend, expense categories, receipts, reimbursements. Useful for expense-side reports and for catching spend that has not yet hit the books.

Ramp also carries real business and treasury account balances with history, plus vendor bill detail and natural-language spend analytics. Its write actions — approve or reject a bill, mark a bill ready to sync — belong to ap-processor, never to a report. Read only, here.

Expensify is read-only search. Expense reports, individual expenses, invoices, trips, category-grouped totals, and approval-state statuses. Receipt substantiation is a first-class filter: "expenses over USD 75 with no receipt attached" is a real query and a genuinely useful report.

Reimbursements appear in both. Ramp and Expensify overlap here. Pick one as the reimbursement source per report, say which, and use the other for detail it uniquely holds — the same rule the processors follow.

MYOB

The ledger for MYOB shops. Read-only. Same P&L and receivables shape as QuickBooks, with three hard limits worth stating in the report rather than discovering mid-run.

• No bank or cash balances. MYOB gives the AR and AP legs, never cash on hand. A cash-position metric sourced from MYOB is not available — say so rather than substituting AR.
• No customer contact detail. Names and balances only.
• Three financial years. Reporting covers the current and prior two financial years. A four-year comparison is not available; say so instead of returning a short series that looks complete.
• Any period reference — "last quarter", "FYTD" — means the business financial year unless the owner says calendar. Resolve the financial-year dates once and reuse them across the run.

Zoho Books

The ledger for Zoho shops. Document-level reads, no report endpoints — the metric families are assembled from lists, and the report says so.

• No P&L, cash-flow, or aging report endpoints. "Net income" is invoiced revenue minus recorded expenses, labelled as such; a true P&L comes from the Reports export.
• No bill object and no vendor payments. AP is purchase orders and expenses only.
• No bank-transaction feed. Balances only, with an uncategorized_transactions count per account.
• The organisation record (get_organization) supplies country_code, currency_code, and fiscal_year_start_month, so period references resolve against the business's year end.

The uploaded-file path

This is a first-class mode, not a degraded one. A large share of owners have tool sprawl and no clean connector.

When no connector covers a metric:

1. Say plainly what you need: "Export your sales report for the period and drop it here."
2. Accept CSV or XLSX. Read the header row and map columns to the spec's metrics.
3. If a needed column is absent, name it specifically — "there's no cost column, so I can't compute margin" — rather than silently dropping the metric.
4. Record the file's column mapping in the saved spec so the next run can reuse it.

A report built from a file is a real report. Deliver the same chat summary and the same workbook.

Parallel-pull rule

Every source call goes out in one batch. Reports commonly touch four or five systems, and serial pulls turn a thirty-second skill into a two-minute wait that owners will not sit through twice.

Record failures internally. Surface them in the report appendix, never mid-stream.