Appearance
Reports
GET /v3/company/{companyId}/reports/{reportName} serves 84 reports (30 QuickBooks Online-compatible and 54 Desktop extension reports) from QuickBooks Desktop. Most are straight out of Desktop's own report engine, one qbXML round trip per call; CashFlow is built from several queries and AccountList from Desktop's account list (see CashFlow is derived); the response is QBO's Header / Columns / Rows shape, so existing QBO report code keeps working.
Report names match case-insensitively, and the response echoes QBO's exact casing back in Header.ReportName. SalesByCustomer and SalesByProduct (QBO's UI names) are accepted as aliases of CustomerSales and ItemSales.
Supported reports
Every report below has been run against QuickBooks Enterprise 24.
| Report | qbXML request | Desktop report type |
|---|---|---|
ProfitAndLoss | GeneralSummaryReportQueryRq | ProfitAndLossStandard |
BalanceSheet | GeneralSummaryReportQueryRq | BalanceSheetStandard |
TrialBalance | GeneralSummaryReportQueryRq | TrialBalance |
AgedReceivables | AgingReportQueryRq | ARAgingSummary |
AgedPayables | AgingReportQueryRq | APAgingSummary |
CustomerBalance | GeneralSummaryReportQueryRq | CustomerBalanceSummary |
VendorBalance | GeneralSummaryReportQueryRq | VendorBalanceSummary |
CustomerIncome | GeneralSummaryReportQueryRq | IncomeByCustomerSummary |
VendorExpenses | GeneralSummaryReportQueryRq | ExpenseByVendorSummary |
CustomerSales (SalesByCustomer) | GeneralSummaryReportQueryRq | SalesByCustomerSummary |
ItemSales (SalesByProduct) | GeneralSummaryReportQueryRq | SalesByItemSummary |
InventoryValuationSummary | GeneralSummaryReportQueryRq | InventoryValuationSummary |
ProfitAndLossDetail | GeneralDetailReportQueryRq | ProfitAndLossDetail |
GeneralLedger | GeneralDetailReportQueryRq | GeneralLedger |
JournalReport | GeneralDetailReportQueryRq | Journal |
TransactionList | GeneralDetailReportQueryRq | TxnListByDate |
CustomerBalanceDetail | GeneralDetailReportQueryRq | CustomerBalanceDetail |
VendorBalanceDetail | GeneralDetailReportQueryRq | VendorBalanceDetail |
AgedReceivableDetail | AgingReportQueryRq | ARAgingDetail |
AgedPayableDetail | AgingReportQueryRq | APAgingDetail |
InventoryValuationDetail | GeneralDetailReportQueryRq | InventoryValuationDetail |
TransactionListByCustomer | GeneralDetailReportQueryRq | TxnListByCustomer |
TransactionListByVendor | GeneralDetailReportQueryRq | TxnListByVendor |
TaxSummary | GeneralSummaryReportQueryRq | SalesTaxLiability |
BudgetOverview | BudgetSummaryReportQueryRq | ProfitAndLossBudgetOverview |
BudgetVsActuals | BudgetSummaryReportQueryRq | ProfitAndLossBudgetVsActual |
ClassSales | CustomSummaryReportQueryRq | CustomSummary (rows by class, income accounts) |
TransactionListWithSplits | CustomDetailReportQueryRq | CustomTxnDetail (rows by account, with a Split column) |
AccountList | AccountQueryRq | Desktop's account list (built, no report type) |
CashFlow | derived, see below | Profit and Loss plus two Trial Balances |
TaxSummary is Desktop's Sales Tax Liability report (taxable and non-taxable sales, tax collected) and honors accounting_method; it takes summarize_column_by=Total only. InventoryValuationDetail, TransactionListByCustomer and TransactionListByVendor do not accept accounting_method: Desktop refuses ReportBasis on them (status 3151).
BudgetOverview and BudgetVsActuals take a fiscal year instead of dates; see Budget reports.
The 54 Desktop extension reports are listed in their own section below.
Any other QBO report name returns REPORT_UNKNOWN with the supported names in the fault detail. BalanceSheetDetail is a Desktop report with no QBO twin; see Desktop extension reports.
ClassSales is Desktop's custom summary report: one row per class (plus Unclassified and a TOTAL) over the income accounts. It takes start_date/end_date or date_macro, accounting_method, summarize_column_by (Month, Week, Days, Quarter, Year), and the customer, item, class and transaction_type filters; the account filter is fixed to income, so account, account_type, vendor and the modified-date filter are refused. For a class split of the whole profit and loss use ProfitAndLoss?summarize_column_by=Classes.
TransactionListWithSplits is Desktop's custom transaction detail report: every transaction line with a Split column, grouped under each account it touches (so a two-sided transaction appears under both accounts, as in QuickBooks). It takes start_date/end_date or date_macro, accounting_method, customer, vendor, item, class, account or account_type, transaction_type, start_moddate/end_moddate and columns; each filter was checked against QuickBooks Enterprise 24. Without columns it returns date, type, number, name, memo, account, split and amount. It takes no column split. Over a full year it can be thousands of rows, so narrow the dates or filter.
One QBO report name is not available, and the fault names the working alternative:
| QBO name | Use instead |
|---|---|
DepartmentSales | ClassSales (Desktop has no departments; the opt-in Department alias applies to entities, not reports) |
Parameters
| Parameter | Reports | Notes |
|---|---|---|
start_date, end_date | period reports (ProfitAndLoss, BalanceSheet, TrialBalance, CustomerIncome, VendorExpenses, CustomerSales, ItemSales, ProfitAndLossDetail, GeneralLedger, JournalReport, TransactionList) | ISO YYYY-MM-DD. Must be sent together. |
report_date | as-of reports (both aging pairs, CustomerBalance, VendorBalance, their detail reports, InventoryValuationSummary) and BalanceSheet | Single as-of date. On BalanceSheet it is an alternative to the range, not an addition to it. |
date_macro | all | QBO date macros, spaced or compact, case-insensitive (This Fiscal Year-to-date, Last Month, LastMonth, ThisYearToDate, …; "Fiscal" is optional). Fiscal-relative on both sides, so they map 1:1. |
accounting_method | ProfitAndLoss, BalanceSheet, TrialBalance, ProfitAndLossDetail, GeneralLedger, CustomerBalanceDetail, VendorBalanceDetail, CustomerIncome, VendorExpenses, CustomerSales, ItemSales | Cash or Accrual → Desktop's ReportBasis. Desktop refuses ReportBasis on JournalReport, TransactionList, CustomerBalance, VendorBalance, InventoryValuationSummary and the aging reports, so those fault. |
summarize_column_by | period summary reports, plus Month/Week/Days/Quarter/Year on CustomerBalance and VendorBalance | Total (default), Month, Week, Days, Quarter, Year, Customers, Vendors, Classes → qbXML SummarizeColumnsBy (Month, Week, Day, Quarter, Year, Customer, Vendor, Class). Desktop refuses Customers on CustomerSales and CustomerIncome and Vendors on VendorExpenses. Detail, aging and inventory valuation reports accept only Total. |
customer, vendor | all except InventoryValuationSummary and InventoryValuationDetail; aging reports take only their own (customer on AR, vendor on AP) | One or more comma-separated Ids → ReportEntityFilter. |
item | period, balance and inventory reports (not the aging reports) | Comma-separated Ids → ReportItemFilter. |
class | period reports (not the aging, balance or inventory reports) | Comma-separated Ids → ReportClassFilter. |
account | summary reports (not InventoryValuationSummary) and every detail report except the two aged-detail reports | Comma-separated account Ids → ReportAccountFilter. Not allowed together with account_type. The aging reports refuse it: Desktop's aging account filter does not filter meaningfully. |
account_type | same as account | One QBO account type (Bank, AccountsReceivable, OtherCurrentAsset, FixedAsset, OtherAsset, AccountsPayable, CreditCard, OtherCurrentLiability, LongTermLiability, Equity, Income, CostOfGoodsSold, Expense, OtherIncome, OtherExpense) → AccountTypeFilter. |
transaction_type | summary, detail and aging reports (not InventoryValuationSummary) | Comma-separated QBO transaction types → ReportTxnTypeFilter: Invoice, CreditMemo, SalesReceipt, Payment, Deposit, Transfer, Estimate, Bill, VendorCredit, BillPayment (both check and credit-card bill payments), BillPaymentCheck, BillPaymentCreditCard, Check, CreditCardCharge, CreditCardCredit, PurchaseOrder, JournalEntry, InventoryQuantityAdjustment. Types with no single Desktop twin (Expense, CashPurchase, RefundReceipt) fault. |
start_moddate, end_moddate | detail reports (not the two aged-detail reports) | ISO dates → ReportModifiedDateRangeFilter: only transactions last modified in the window. Must be sent together (REPORT_INVALID_DATE otherwise). |
columns | detail reports and AgedReceivableDetail / AgedPayableDetail | Comma-separated QBO ColKeys → IncludeColumn (tx_date, txn_type, doc_num, txn_num, name, cust_name, vend_name, memo, account_name, split_acc, klass_name, is_cleared, debt_amt, credit_amt, subt_nat_amount, rbal_nat_amount, subt_open_bal, due_date, past_due, po_num, term_name). Aliases that map to the same Desktop column are sent once; an unknown key faults and lists the accepted ones. If txn_type is not among the requested columns, the transaction id is attached to the first cell instead. |
minorversion | all | Accepted and ignored, as everywhere else in TenkeyBridge. |
Examples of the filter and column parameters
All of these use made-up data (ExampleCo, Pat Owner, invented ids).
bash
# account: ExampleCo's operating and payroll accounts only (ids 31 and 44)
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/GeneralLedger?start_date=2026-01-01&end_date=2026-03-31&account=31,44"
# account_type: every Expense account in the quarter
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/ProfitAndLoss?start_date=2026-01-01&end_date=2026-03-31&account_type=Expense"
# transaction_type: only invoices and credit memos
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/TransactionList?start_date=2026-01-01&end_date=2026-03-31&transaction_type=Invoice,CreditMemo"
# start_moddate / end_moddate: what changed in the books during the first week of October
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/TransactionList?start_date=2026-01-01&end_date=2026-12-31&start_moddate=2026-10-01&end_moddate=2026-10-07"
# columns: just date, type, number, name and amount; rows now carry transaction ids
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/TransactionListByCustomer?start_date=2026-01-01&end_date=2026-03-31&columns=tx_date,txn_type,doc_num,cust_name,subt_nat_amount"When columns is sent, each data row's txn_type cell also carries id, the QuickBooks transaction id (for example "ColData": [{ "value": "Invoice", "id": "2FBE8-1760000000" }, ...]), so you can fetch the full transaction. Rows with no transaction behind them, such as the cost postings in GeneralLedger, have no id. Without columns, no ids are added.
Request elements are sent in the order Desktop requires: period, filters, IncludeColumn, ReportAgingAsOf, SummarizeColumnsBy, then ReportBasis.
If you send no dates at all you get fiscal year-to-date — the same window QuickBooks Online returns for a dateless call. This is deliberate: Desktop's own bare default is month-to-date, so TenkeyBridge always sends an explicit period rather than let the two platforms silently disagree about what "no dates" means. An undated as-of report defaults to today, again matching QBO.
Detail reports
The detail reports (ProfitAndLossDetail, GeneralLedger, JournalReport, TransactionList, CustomerBalanceDetail, VendorBalanceDetail, AgedReceivableDetail, AgedPayableDetail) list transactions row by row. Their shape follows QBO's:
Columns.Column[n]has aColTypeofString,DateorMoneyand aMetaDataentry{ "Name": "ColKey", "Value": … }. ColKeys are best-effort: QBO does not document its column keys, so they are mapped from Desktop's exact column types —Date→tx_date,TxnType→txn_type,RefNumber→doc_num,Name→name(cust_name/vend_nameon the customer and vendor reports),Memo→memo,Account→account_name,SplitAccount→split_acc,Debit→debt_amt,Credit→credit_amt,Amount→subt_nat_amount,RunningBalance→rbal_nat_amount,OpenBalance→subt_open_bal,DueDate→due_date,Aging→past_due,Class→klass_name,ClearedStatus→is_cleared,PONumber→po_num,Terms→term_name,TxnNumber→txn_num. A column Desktop adds that is not in this table keeps a snake-cased version of its own title as its key.- Desktop's leading blank column is folded away. Section names (an account, a customer, an aging bucket) appear in
Header.ColData[0]and "Total …" captions inSummary.ColData[0], as in QBO. A customer or account section opens with a Desktop row carrying the name and its opening balance; those cells become the sectionHeader. - Every transaction row is
"type": "Data", even at the top level of a flat report such asTransactionList(whose period-naming wrapper row is dropped). JournalReportcloses each transaction with an unlabeled subtotal; each transaction's rows become a header-lessSectionwhoseSummaryholds its debit and credit totals.- An empty aging bucket still arrives as a section with no rows and a "Total …" summary.
ColDatacarriesvalueonly by default. QBO also gives anidfor names, accounts and transactions; sendcolumnsand each data row'stxn_typecell carries the QuickBooks transaction id. Names and accounts get noid: Desktop's report rows carry noListID, so none is invented.- Report headers echo Desktop's
ReportBasisexcept on the aging reports (QBO's own aging headers carry none).
Example
bash
curl -s -H "Authorization: Bearer $TOKEN" \
"https://api.tenkeybridge.com/v3/company/$COMPANY_ID/reports/ProfitAndLoss?start_date=2026-01-01&end_date=2026-12-31"json
{
"Header": {
"Time": "2026-07-30T12:00:00-07:00",
"ReportName": "ProfitAndLoss",
"ReportBasis": "Accrual",
"StartPeriod": "2026-01-01",
"EndPeriod": "2026-12-31",
"SummarizeColumnsBy": "Total",
"Currency": "USD",
"Option": [{ "Name": "NoReportData", "Value": "false" }]
},
"Columns": {
"Column": [
{ "ColTitle": "", "ColType": "Account" },
{ "ColTitle": "Jan - Dec 26", "ColType": "Money" }
]
},
"Rows": {
"Row": [
{
"Header": { "ColData": [{ "value": "Income" }, { "value": "" }] },
"Rows": {
"Row": [
{
"Header": { "ColData": [{ "value": "40100 · Construction Income" }, { "value": "" }] },
"Rows": {
"Row": [
{ "ColData": [{ "value": "40110 · Design Income" }, { "value": "36669.25" }], "type": "Data" }
]
},
"Summary": { "ColData": [{ "value": "Total 40100 · Construction Income" }, { "value": "418731.65" }] },
"type": "Section"
}
]
},
"Summary": { "ColData": [{ "value": "Total Income" }, { "value": "425136.05" }] },
"type": "Section",
"group": "Income"
},
{ "Summary": { "ColData": [{ "value": "Net Income" }, { "value": "127673.01" }] }, "type": "Section", "group": "NetIncome" }
]
}
}(Trimmed — the real Rock Castle response is 8 root rows.)
Reading the row tree
qbXML hands back a flat stream of rows; QBO wants a tree. TenkeyBridge rebuilds it:
- A
Sectionhas aHeader(the section's name), nestedRows, and aSummary(its subtotal line). - A summary-only
Section—Summarywith noHeaderand noRows— is a computed line likeGross Profit,Net Income, or a report's grandTOTAL. QBO emits these the same way. - A data row carries
ColDataonly. Rows at the top level have notype; nested rows carry"type": "Data". That asymmetry is QBO's, and it is reproduced verbatim. - Cells are always padded to the full column count, so
ColData[n]always lines up withColumns.Column[n]. A cell Desktop had no value for is{"value": ""}.
Desktop extension reports
QuickBooks Desktop has reports that QuickBooks Online does not, so QBO clients have no name for them. TenkeyBridge serves 50 of them under their Desktop names, at the same /v3/company/{companyId}/reports/{reportName} path, in the same QBO report JSON (Header, Columns, Rows). Names match case-insensitively like every other report. Every one has been run against QuickBooks Enterprise 24.
| Report | What it shows | As-of or period | accounting_method |
|---|---|---|---|
ProfitAndLossByClass | Income and expenses with one column per class | Period | Yes |
ProfitAndLossByJob | Income and expenses with one column per customer or job | Period | Yes |
ProfitAndLossPrevYearComp | Profit and loss beside the same period last year, with change | Period | Yes |
ProfitAndLossYTDComp | This period's profit and loss beside the year to date | Period | Yes |
BalanceSheetPrevYearComp | Balance sheet beside the same date last year, with change | As-of | Yes |
BalanceSheetByClass | Balance sheet with one column per class | As-of | Yes |
PurchaseByVendorSummary | Purchases totaled per vendor | Period | Yes |
PurchaseByItemSummary | Purchases totaled per item, with quantity and average cost | Period | Yes |
SalesByRepSummary | Sales totaled per sales rep | Period | Yes |
InventoryStockStatusByItem | Quantity on hand, on order and reorder point per item | Period | No |
OpenInvoices | Unpaid invoices and their open balances, by customer | As-of | No |
UnpaidBillsDetail | Unpaid bills and their open balances, by vendor | As-of | No |
OpenPOs | Purchase orders not yet received or closed | Period | No |
SalesByCustomerDetail | Each sales transaction, grouped by customer | Period | Yes |
SalesByItemDetail | Each sales line, grouped by item | Period | Yes |
IncomeByCustomerDetail | Each income transaction, grouped by customer | Period | Yes |
ExpenseByVendorDetail | Each expense transaction, grouped by vendor | Period | Yes |
PurchaseByVendorDetail | Each purchase transaction, grouped by vendor | Period | Yes |
DepositDetail | Each bank deposit with the payments it contains | Period | No |
CheckDetail | Each check written, with payee, account and amount | Period | No |
BalanceSheetDetail | Every transaction behind each balance sheet account | As-of | Yes |
CollectionsReport | Overdue receivables per customer, with contact details for follow-up | As-of | No |
TxnDetailByAccount | Every transaction posted to each account, with running balance | Period | Yes |
UnbilledCostsByJob | Billable costs not yet invoiced, by customer or job | Period | Yes |
AuditTrail | Who entered or last changed each transaction, and when | Period | No |
1099Detail | Payments to 1099 vendors | Period | No |
SalesByRepDetail | Each sales line, grouped by sales rep | Period | Yes |
PurchaseByItemDetail | Each purchase line, grouped by item | Period | Yes |
OpenPOsByJob | Open purchase orders, grouped by customer or job | Period | No |
EstimatesByJob | Estimates, grouped by customer or job | Period | No |
JobProgressInvoicesVsEstimates | Progress invoicing against each estimate | Period | No |
OpenSalesOrderByCustomer | Open sales orders, grouped by customer | Period | No |
OpenSalesOrderByItem | Open sales orders, grouped by item | Period | No |
PendingSales | Sales marked pending, such as estimates not yet accepted | Period | Yes |
IncomeTaxDetail | Transactions behind each income tax line | Period | Yes |
MissingChecks | Gaps in the check numbers of one or more bank accounts (requires account) | Period | No |
SalesTaxRevenueSummary | Sales and tax by sales tax item | Period | Yes |
IncomeTaxSummary | Totals per income tax line | As-of | Yes |
BalanceSheetSummary | Balance sheet with account-type totals only | As-of | Yes |
InventoryStockStatusByVendor | Stock status of each item, grouped by preferred vendor | Period | No |
JobProfitabilitySummary | Income, cost and profit per customer or job | Period | No |
JobEstimatesVsActualsSummary | Estimated against actual amounts per customer or job | Period | No |
ItemProfitability | Quantity, income, cost and margin per item | Period | No |
ItemEstimatesVsActuals | Estimated against actual amounts per item | Period | No |
JobProfitabilityDetail | Income and cost lines behind one customer or job (requires customer) | Period | No |
JobEstimatesVsActualsDetail | Estimated against actual amounts for one customer or job (requires customer) | Period | No |
TimeByJobSummary | Hours per customer or job | Period | No |
TimeByJobDetail | Each time entry, grouped by customer or job | Period | No |
TimeByItem | Hours per service item | Period | No |
TimeByName | Hours per employee or vendor | Period | No |
PhysicalInventoryWorksheet | Stocked items with description, preferred vendor and on-hand quantity, plus an empty Physical Count column | Snapshot | No |
InventoryValuationSummaryBySite | Inventory valuation per site (needs Advanced Inventory) | Snapshot | No |
LotNumberInStockBySite | Lot numbers in stock per site (needs Advanced Inventory) | Snapshot | No |
SerialNumberInStockBySite | Serial numbers in stock per site (needs Advanced Inventory) | Snapshot | No |
As-of reports take report_date and ignore start_date / end_date; period reports take start_date / end_date or date_macro. accounting_method is accepted only where the last column says Yes: on the others Desktop refuses ReportBasis, so the call faults with REPORT_UNSUPPORTED_OPTION. summarize_column_by, the filters and columns are accepted per report, exactly as for the standard reports of the same kind; InventoryStockStatusByItem takes the item filter only and no column split. A report that does not accept an option faults before QuickBooks is contacted.
The filters and columns on the wave 4 reports are limited to what was proven against QuickBooks Enterprise 24 (live probe, 2026-10-20):
- Detail reports (
TxnDetailByAccount,AuditTrail,SalesByRepDetail,PurchaseByItemDetail,OpenPOsByJob,EstimatesByJob,JobProgressInvoicesVsEstimates,OpenSalesOrderByCustomer,OpenSalesOrderByItem,IncomeTaxDetail,UnbilledCostsByJob,PendingSales) takecustomer,vendor,item,class,account_type/account,transaction_typeandstart_moddate/end_moddate.UnbilledCostsByJobandPendingSalesdo not take the account filter (Desktop fails it with an internal error).columnsworks on all of them exceptAuditTrail. MissingChecksrequiresaccount, one bank account Id or several comma-separated. Desktop refuses a bare query, anaccount_typeandaccounting_method, so the gateway faults on all three. It takestransaction_type,class,start_moddate/end_moddateandcolumnsas well (no customer, vendor or item filter).- Summaries (
SalesTaxRevenueSummary,IncomeTaxSummary,BalanceSheetSummary,InventoryStockStatusByVendor) take the same filters without the modified-date range. - Job summaries (
JobProfitabilitySummary,JobEstimatesVsActualsSummary,ItemProfitability,ItemEstimatesVsActuals) takecustomer,item,class,account_type/account,transaction_typeand the modified-date range, plussummarize_column_by=Month. - Job detail reports (
JobProfitabilityDetail,JobEstimatesVsActualsDetail) requirecustomer(a customer or job Id) and take no other filter or column. - Time reports take
customer,itemandclass. They take nocolumns(Desktop refuses the duration column) and noaccounting_method;summarize_column_by=Monthworks except onTimeByJobDetail. PhysicalInventoryWorksheetis a current snapshot. Desktop refuses every date, filter, basis and column-split element on it (status 3151), so the gateway faults on any parameter before contacting QuickBooks.- The Site, Lot and Serial reports need QuickBooks Enterprise Advanced Inventory. A company file without it answers Desktop status 3250, which the gateway returns as
422REPORT_FEATURE_UNAVAILABLEnaming the feature. They are sent bare (nothing past the feature gate could be probed) and are not available in the sandbox. 1099Detailtakes no filter. An entity filter on it crashed QuickBooks Desktop when it was probed, so the gateway refuses every filter on this report withREPORT_UNSUPPORTED_OPTIONbefore anything is sent to Desktop.
A report that does not accept an option faults before QuickBooks is contacted. The advanced inventory reports (by site, lot and serial number) are left out on purpose: they fail on files that do not use that feature.
Budget reports
BudgetOverview and BudgetVsActuals serve Desktop's profit and loss budget reports under their QBO names. QuickBooks Desktop scopes a budget by fiscal year, so they take fiscal_year (four digits, default: the current year) in place of the date parameters, an optional class filter, and no other filters or column split. Columns are one group per month plus a period total; titles are qualified so they stay distinct (Jan 26 - Budget, Jan 26 - $ Over Budget). Balance sheet budgets remain available through the Budget entity.
class takes one or more comma-separated class Ids. Desktop keeps class budgets apart from account budgets, so a request with class is sent as an account-and-class budget and both the budget and the actual columns follow the filter. Without class the account budget is read and, if QuickBooks has none for that year (it answers with an empty report), the class budget is read instead, so a file whose budget was set up only by class still reads. A customer filter is not offered: qbXML cannot create a customer budget, and asking for one returned nothing beyond the account budget. The sandbox replays one fixed sample and ignores class, like its other filters.
Honest boundaries
- CashFlow is derived. See the next subsection.
- Values are Desktop's, verbatim. No rounding, no recomputation, no client-side arithmetic. If Desktop says
127673.01, the API says127673.01. - Column titles are Desktop's, verbatim. Desktop's aging buckets read
Current,1 - 30,31 - 60,61 - 90,> 90,TOTALwhere QBO writes91 and overandTotal; a period column readsJan - Dec 26where QBO writesTotal. Aging buckets must stay Desktop's — a company file can be configured with entirely different buckets, so printing QBO's labels over them would be a lie — and the same rule is applied to every column for consistency. On the summary reports QBO'sMetaData.ColKeyhas no Desktop equivalent and is not invented. - Aging buckets are company-file configuration, not request parameters.
aging_period,num_periods, andaging_methodall fault withREPORT_UNSUPPORTED_OPTION. Change them in QuickBooks under Edit > Preferences > Reports & Graphs; whatever the file is configured with comes back as the report's columns. accounting_methodis rejected on the aging reports. qbXML'sAgingReportQueryRqhas noReportBasiselement, so there is no honest way to produce a cash-basis aging report.- Key on section header text, not on
group.groupis emitted only where the section name confidently maps to a QBO group (Income,COGS,Expenses,TotalAssets,GrandTotal, …). Desktop-specific sections — anything named after a numbered account, for instance — carry nogroupat all, exactly as QBO omits it for sections it does not recognise. Header.Optioncarries noAccountingStandard. QBO reports GAAP; Desktop never states an accounting standard, so it is omitted rather than assumed.- A few options are unsupported.
department(Desktop's equivalent isclass),qzurl, andadjusted_gain_lossfault loudly, as doEmployees/ProductsAndServices/Departments/Locationcolumn splits — qbXML'sSummarizeColumnsByhas no per-item, per-employee or per-location split. - Detail columns are Desktop's.
CustomerBalanceDetailandVendorBalanceDetailcome back from Desktop with one section per customer or vendor and its balance, and no individual transaction rows; TenkeyBridge passes that through rather than fill it in. - Sandbox reports are static. In a developer sandbox every report replays a fixed report of the ExampleCo sample company. Most are real QuickBooks captures; eleven (GeneralLedger, JournalReport, TransactionList, ProfitAndLossDetail, ItemSales, InventoryValuationSummary, CustomerIncome, VendorExpenses, VendorBalance, VendorBalanceDetail, AgedPayableDetail) are generated from the sample data until they can be recaptured. Dates, filters,
accounting_methodandsummarize_column_byare accepted but ignored, so the sandbox'sHeaderreports what it actually served (SummarizeColumnsByisTotal,ReportBasisis the capture's, no request echo) and carriesOptionSandboxStaticReport: "true".AccountListis the exception: the sandbox's emulator answers it from the sandbox's own accounts, so it reflects your writes and does not carrySandboxStaticReport. - Report calls are not batchable. A
Reportsitem inside a batch envelope faults per-item pointing back at this endpoint — reports are a platform surface, not an entity, so the batch envelope has nothing to execute.
CashFlow is derived
QuickBooks Desktop's SDK has no cash-flow report (qbXML has no statement-of-cash-flows report type, and StatementOfCashFlows is refused with status 3110). So CashFlow is the one report here that TenkeyBridge computes rather than translates.
- Method. The indirect method. TenkeyBridge runs Desktop's Profit and Loss for the period and two Trial Balances, one as of the day before
start_dateand one as ofend_date, then classifies the balance changes by account type into operating, investing and financing sections. - What counts as cash. Bank accounts plus Undeposited Funds, as in QuickBooks Online. Desktop's own Statement of Cash Flows leaves Undeposited Funds out of cash, so that line is the one expected difference if you compare the two.
- Depreciation. Fixed Asset accounts, accumulated depreciation included, are classified as investing, which is Desktop's own default classification. Depreciation is not added back as a separate operating line.
- Self-check. Before answering, the derived net income is compared with the net income on Desktop's Profit and Loss. If they differ by even a cent, or a Trial Balance row cannot be matched to an account, the call fails with
REPORT_COMPOSE_FAILED(HTTP 502) instead of returning a statement that does not add up. - Cost. Five QuickBooks round trips per call (company settings, Profit and Loss, the account list and two Trial Balances), so expect it to be slower than the single-query reports, particularly through the Web Connector.
- Marked as derived.
Header.TkbDerivedReportistrueon the response. In the developer sandbox,CashFlowis derived from the fixed sample reports and carriesSandboxStaticReport: true, so dates are ignored there.
AccountList is built from Desktop's account list. Desktop has no account detail type, so that column is absent.
Budget is an entity, not a report
QuickBooks Desktop's budget figures come out of a report message (BudgetSummaryReportQuery), but TenkeyBridge serves them as QBO's read-only Budget entity — not through this endpoint — because that is where QBO-compatible clients look for them.
bash
# Every budget in the probed window
curl -s "$TKB/v3/company/$COMPANY_ID/query?query=SELECT%20*%20FROM%20Budget" \
-H "Authorization: Bearer $TOKEN"
# One budget, by its synthetic id
curl -s "$TKB/v3/company/$COMPANY_ID/budget/2026-ProfitAndLoss" \
-H "Authorization: Bearer $TOKEN"json
{
"Budget": {
"Id": "2026-ProfitAndLoss",
"SyncToken": "0",
"Name": "FY2026 Profit and Loss Budget",
"StartDate": "2026-01-01",
"EndDate": "2026-12-31",
"BudgetType": "ProfitAndLoss",
"BudgetEntryType": "Monthly",
"Active": true,
"BudgetDetail": [
{
"BudgetDate": "2026-01-01",
"Amount": 12000.0,
"AccountRef": { "value": "80000030-1797300000", "name": "Consulting Income" }
}
],
"sparse": false,
"domain": "QBO"
}
}Three things about it are unlike every other entity, and they follow from qbXML having no Budget record at all:
- Ids are synthetic:
{fiscalYear}-{BudgetType}, e.g.2026-ProfitAndLossor2027-BalanceSheet. Desktop budgets carry noListIDorTxnID, so TenkeyBridge mints a deterministic id you can construct yourself.SyncTokenis always"0". SELECT *probes a window, it does not enumerate.BudgetSummaryReportQueryRqrequires aFiscalYear, so there is no "list budgets" call. ASELECT * FROM Budgetasks Desktop for the current calendar year, the year before, and the year after × both statement types — six report requests in one round trip — and returns the ones that come back with budgeted amounts. A budget outside that window is still reachable by id. Because the probe is speculative, the query never fails on an individual year: a company with no budgets gets an empty list, the same answer QuickBooks Online gives.GET /budget/{id}asks about one budget, so it does report that budget's status — a Desktop error surfaces as a fault, and a year with no budget is a 404.- Reads only, forever. There is no
BudgetAdd/BudgetMod/BudgetDelin qbXML, so create, update, and delete fault withUNSUPPORTED_BY_DESKTOP. QBO's own Budget entity is read-only too, so nothing is lost.
WHERE Id = '…' is the only filter (it compiles to the same single report request as GET /budget/{id}); anything else faults with UNSUPPORTED_QUERY. Class and customer budget breakdowns, and Desktop's budget-vs-actual report types, are documented boundaries — see the compatibility entry.
See also
- Compatibility matrix — Reports
- Compatibility matrix — Budget
REPORT_UNKNOWN·REPORT_UNSUPPORTED_OPTION·REPORT_INVALID_DATE- Batch operations — and why report calls stay out of the envelope

