Run reports

The QuickBooks Online API includes a Reports API that is used to query a financial report. This topic provides an overview of the report response by showcasing the profit and loss report.

A profit and loss report, also known as the Income Statement, summarizes income and expenses for the company. The report shows subtotals for each income and expense account in the chart of accounts. The report is divided into sub-sections corresponding to the various income and expense groups, and within the groups a row corresponding to each account having data. Accounts with no data are excluded from the report. The total for each sub-section is rolled up into its individual summary, with the last line of the report showing the net income or loss.

Note

As a best practice, limit the date range specified in a report request to six months.

To follow along, you’ll need a sandbox or another QuickBooks company populated with a chart of accounts, customers, and items. The examples in this tutorial use the sandbox company.

Summary of available reports

QuickBooks Report Name Reports API Endpoint Java .NET PHP
Business Overview      
Balance Sheet BalanceSheet
Profit and Loss ProfitAndLoss
Profit and Loss Detail ProfitAndLossDetail    
Trial Balance Trial Balance
Statement of Cash Flows CashFlow
Inventory Valuation Summary InventoryValuation
Review Sales      
Sales by Customer Summary CustomerSales
Sales by Product/Service Summary ItemSales
Sales by Department Summary DepartmentSales
Sales by Class Summary ClassSales
Income by Customer Summary CustomerIncome
Manage Accounts Receivable      
Customer Balance Summary CustomerBalance
Customer Balance Detail CustomerBalanceDetail    
A/R Aging Summary AgedReceivables
A/R Aging Detail AgedReceivableDetail    
Manage Accounts Payable      
Vendor Balance Summary VendorBalance
Vendor Balance Detail VendorBalanceDetail
A/P Aging Summary AgedPayables
A/P Aging Detail AgedPayableDetail
Review Expenses and Purchases        
Expenses by Vendor VendorExpenses
Accountant Reports        
Account List AccountListDetail    
General Ledger GeneralLedgerDetail  
Tax Summary (France region, only) TaxSummary      

Overview of the report response

The structure of each sub-section echoes that in the chart of accounts. That is, the nesting structure of the chart of accounts is preserved in the report, which can create several nested levels of data. The data returned in the report is subject to one or more filter query parameters submitted with the request.

A report response consists of three sections:

  • Header—Overview metadata for the report.
  • Columns—Column metadata describing each column in the report.
  • Rows—The report data. There are two types of rows:
    • Section—used to define a sub-report and can include deeper nested sub-reports, data rows, or both.
    • Data—used to define report data and includes only columns.

Transaction compliance dates

Reports list transaction compliance dates rather than the actual transaction dates. Consider the following examples:

Non-payment transaction date Non-payment transaction due date Payment transaction date Compliance date
February 6, 2017 February 6, 2017 February 1, 2017—prepaid February 6, 2017
February 1, 2017 February 1, 2017 February 6, 2017 February 6, 2017

Of particular note, for a transaction where the payment date is before the transaction date, the compliance date is the original transaction date. This correctly accounts for the revenue and any tax liabilities within the intended financial period.

Sample report responses

Report with no data

This is the response for a report that contains no data: there is no data for the resulting date range, which in this case is January 1, 2014 to February 5, 2014. The resulting report has a single column with the default Profit and Loss groups. It is not very interesting, but serves to show the basic report structure.

URI:

1
https://quickbooks.api.intuit.com/v3/company/<realmID>/reports/ProfitAndLoss
qbo/docs/develop/tutorials/ReportNoData.png

Report with customer filtering

This section showcases a P&L report for a specific customer for the last quarter. To view the complete response, click here.

URI:

1
2
3
4
5
https://quickbooks.api.intuit.com/v3/company/<realmID>/reports/ProfitAndLoss​?
   start_date=2015-01-01&
   ​end_date=2015-07-31&
   customer=1&
   summarize_column_by=Customers

The image below shows the column structure. The report response has been excerpted in the interest of space.

qbo/docs/develop/tutorials/ReportColumns.png

The next image showcases a part of the Income section of the same report response. Here you can see the nested nature of the accounts and how they map to rows in the response. The report response has been excerpted in the interest of space.

qbo/docs/develop/tutorials/ReportRows.png

The report object structure

The table below lists all possible attributes that can be returned in the report response. All values are not localized unless indicated. Click here to download the latest XSD.

Attribute Data Type Description
Header Report header  
→Time DateTime Date and timestamp of the report.
→ReportName String Name of the report.
→ReportBasis ReportBasisEnum Accounting method. Possible values include Cash and Accrual.
→StartPeriod String The date specified by the start_date query parameter submitted with the request. Format is yyyy-mm-dd.
→EndPeriod String The date specified by the end_date query parameter submitted with the request. Format is yyyy-mm-dd.
→SummarizeColumnsBy SummarizeColumnsByEnum The method by which report columns are organized. This contains the value specified by the summarize_column_by query parameter submitted with the request.
→Currency String A string containing the currency code associated with the report.
→Customer
→Vendor
​ →Employee
→Item
→Class
→Department
String A string containing the Ids as specified with the corresponding filter query parameter. Only those filter query parameters specified in the request are returned in the header.
→Option Container for one or more name/value pairs that return additional information about the report contents.  
→→Name
→→Value
String
Supported Names:
AccountingStandard—Indicates the accounting standard being used for this report. Returned with ProfitAndLoss and BalanceSheet reports, only.
NoReportData—Used to signal whether report contains data. If true, report contains no data. If false, report contains data. Returned for every report type.
Columns Top level container holding information for report columns or subcolumns.  
→Column [0..n] Container for an individual report column definition.  
→→ColTitle String

The column label. This string appears at the top of the column. If not defined, the column does not have a label.

The value of this attribute is localized.

→→ColType ColumnTypeEnum

The type of information found in the column. Possible values include:

  • Account—This column in the row represents an account for the row item. The row further defines the specific account.
  • Money—This column in the row represents an amount for the row item.
Rows Top level container holding report rows.  
→Row [0..n]

Represents a row in a report. A group of rows is enclosed in a <Rows> container. Rows may be nested either as a single row or in sets, based on the accounts represented in the report and query parameters specified in the request. Parameters:

  • type—As an enclosing section of sub-rows, this is always the string, Section. As a leaf row, this is always the string, Data.
  • group—The group name, valid when type=Section. Possible values include: Income, COGS, GrossProfit, Expenses, NetOperatingIncome, OtherIncome, OtherExpenses, NetOtherIncome, NetIncome
 
→→ColData [0..n]

Information for each column of a leaf row <Row type=Data>. There must be a <ColData> definition for each column defined in the <Columns> section. Parameters:

  • id—The reference id of the entity as returned in the Identity field. Returned where applicable.
  • value—The value for column. The type of value is based on the column type.
  • href—The link to the quick zoom data for this cell, available when the report endpoint specifies the qzurl query parameter. The qzurl query parameter is supported on a report by report basis; check the list of query parameters for the specific report to determine support. The value of this parameter is localized.
 
→→Header Header row for a report section.  
→​→→ColData [0..n]

Information for each column of the header row. There must be a <ColData> definition for each column defined in the <Columns> section. Parameters:

  • id—The reference id of the entity as returned in the Identity field. Returned where applicable.
  • value—The value for column. The type of value is based on the column type.
 
→​→Rows Container for one or more leaf rows.  
→→Summary Summary row for a report section. It is the cumulative total amount of money in the account, including the sub accounts.  
→​→→ColData [0..n] Information for each column of the summary row. There must be a <ColData> definition for each column defined in the <Columns> section. Parameters: - id—The reference id of the entity as returned in the Identity field. Returned where applicable. - value—The value for column. The type of value is based on the column type.  

Learn more

View the full Reports API reference here.