Skip to main content
GET
List custom summary reports

Authorizations

Authorization
string
header
required

Use your app's API key as the username, and leave the password blank

Headers

Idempotency-Key
string

Makes a retry safe when you never got the answer to a call: a timeout, a dropped connection, a worker that crashed. Send a new key (a UUID, say) with each request you mean to make once, and the same key when you send that request again. A repeat with the key and the same method, path, query and body answers 201 with what the first call created, as it is now, marked Idempotent-Replayed: true, and queues nothing. The same key with a different request is a 422. A key belongs to your app (sandbox and production apps never share one), lasts as long as what it created, and is 1 to 255 printable ASCII characters.

Required string length: 1 - 255
Pattern: ^[\x20-\x7E]+$

Path Parameters

connection_id
string<uuid>
required

The connection (a customer's QuickBooks company file) this request is queued for.

Query Parameters

request_id
string

Your own label for the request, sent to QuickBooks as its qbXML requestID and echoed in the raw answer (response_xml); optional, since the answer's webhook already carries the request's id.

custom_summary_report_type
enum<string>
required

The type of report being queried.

Available options:
CustomSummary
display_report
boolean

Set display_report to true to display this report within the QuickBooks UI. (Default is false.) If you want the request to display the report without returning any data to your application, set the responseData attribute to includeNone.

include_subcolumns
boolean

The default value is false, which means that the report won’t include any subcolumn information. To include all available types of subcolumns for this report, set include_subcolumns to true. The SDK won’t return subcolumn information for data that can be easily computed. (For example, the SDK doesn’t return the “percent of row” column.)

report_account_filter
AccountTypeFilter · object

Allows you to query for a specified account type or for specific list elements.

report_basis
enum<string>

If report_basis is rbCash, the report bases income and expenses on the dates when money changed hands.rbAccrual, the report bases income on the dates when customers were invoiced and bases expenses on the dates when bills were entered.rbNone, the report uses the default report_basis, which is either the QuickBooks Preference setting or the QuickBooks default for a given type of report.

Available options:
Accrual,
Cash,
None
report_calendar
enum<string>

Specifies the type of year that will be used for this report.

Available options:
CalendarYear,
FiscalYear,
TaxYear
report_class_filter
ListID · object

Allows you to query for a specified class. Classes can be used to separate transactions into meaningful categories. (For example, transactions could be classified according to department, business location, or type of work.) In QuickBooks, class tracking is off by default.

report_date_macro
enum<string>

The time period covered by this report.

Choose at most one of: report_period, or report_date_macro.

Available options:
All,
LastMonth,
LastMonthToDate,
LastQuarter,
LastQuarterToDate,
LastWeek,
LastWeekToDate,
LastYear,
LastYearToDate,
NextFourWeeks,
NextMonth,
NextQuarter,
NextWeek,
NextYear,
ThisMonth,
ThisMonthToDate,
ThisQuarter,
ThisQuarterToDate,
ThisWeek,
ThisWeekToDate,
ThisYear,
ThisYearToDate,
Today,
Yesterday
report_detail_level_filter
enum<string>

The level of detail to include in the report.

Available options:
All,
AllExceptSummary,
SummaryOnly
report_entity_filter
EntityTypeFilter · object

Allows you to query for a specified name type (customer, employee, vendor, or other) or query for specific list elements.

report_item_filter
ItemTypeFilter · object

Allows you to query for a specified item type (for example, discount, inventory, or non-inventory) or query for specific list elements.

report_modified_date_range_filter
object

Returns reports that were modified between these two dates (inclusive). The range of acceptable dates for both from_report_modified_date and to_report_modified_date is 1970-01-01 to 2038-01-19T03:14:07 (2038-01-18T19:14:07-08:00 PST).

Choose at most one of: report_modified_date_range_filter, or report_modified_date_range_macro.

report_modified_date_range_macro
enum<string>

The time period covered by this report.

Choose at most one of: report_modified_date_range_filter, or report_modified_date_range_macro.

Available options:
All,
LastMonth,
LastMonthToDate,
LastQuarter,
LastQuarterToDate,
LastWeek,
LastWeekToDate,
LastYear,
LastYearToDate,
NextFourWeeks,
NextMonth,
NextQuarter,
NextWeek,
NextYear,
ThisMonth,
ThisMonthToDate,
ThisQuarter,
ThisQuarterToDate,
ThisWeek,
ThisWeekToDate,
ThisYear,
ThisYearToDate,
Today,
Yesterday
report_period
object

If you omit both to_report_date and from_report_date, the report will cover the current fiscal year to date.

Choose at most one of: report_period, or report_date_macro.

report_posting_status_filter
enum<string>

Allows you to query for posting reports, non-posting reports, or reports that are either one.

Available options:
Either,
NonPosting,
Posting
report_txn_type_filter
object

Allows you to report on specific transaction types (for example, charge, check, deposit, or estimate).

return_columns
enum<string>

Specifies whether you want the report to include only columns with active information, only columns with nonzero values, or all columns regardless of their content or active status.

Available options:
ActiveOnly,
All,
NonZero
return_rows
enum<string>

Specifies whether you want the report to include only rows with active information, only rows with nonzero values, or all rows regardless of their content or active status.

Available options:
ActiveOnly,
All,
NonZero
summarize_columns_by
enum<string>
required

summarize_columns_by determines which data the report calculates and how the columns will be labeled across the top of the report. For example, if you set the value to scbTwoWeek, the report’s column labels might be “Feb 10-23, 02,” “Feb 24-Mar9, 02,” and so on.

Available options:
Account,
BalanceSheet,
Class,
Customer,
CustomerType,
Day,
Employee,
FourWeek,
HalfMonth,
IncomeStatement,
ItemDetail,
ItemType,
Month,
Payee,
PaymentMethod,
PayrollItemDetail,
PayrollYtdDetail,
Quarter,
SalesRep,
SalesTaxCode,
ShipMethod,
Terms,
TotalOnly,
TwoWeek,
Vendor,
VendorType,
Week,
Year
summarize_rows_by
enum<string>
required

summarize_rows_by (along with IncludeColumnList, in most cases) determines what data is calculated for this report and controls how the rows are organized and labeled. For example, if you set the value to srbAccount, the report’s row labels might be “Checking,” “Savings,” and so on.

Available options:
Account,
BalanceSheet,
Class,
Customer,
CustomerType,
Day,
Employee,
FourWeek,
HalfMonth,
IncomeStatement,
ItemDetail,
ItemType,
Month,
Payee,
PaymentMethod,
PayrollItemDetail,
PayrollYtdDetail,
Quarter,
SalesRep,
SalesTaxCode,
ShipMethod,
TaxLine,
Terms,
TotalOnly,
TwoWeek,
Vendor,
VendorType,
Week,
Year
webhook_url
string<uri>

Where QuBe Sync POSTs the answered request (this same document with response_json filled in), signed with X-QUBE-Signature. Send one with every request: it is how answers are delivered. Optional only so a script can queue and look up links.self by hand. It must be an absolute http or https URL. It may not contain a username or password, and in production it may not point at localhost or a private, loopback or link-local address. A qube listen URL must be one of this app's.

Maximum string length: 2048

Callbacks

POST
{$request.query.webhook_url}answered

Body

application/json

POSTed to webhook_url as JSON, signed with X-QUBE-Signature (t=<timestamp>,v1=<hex HMAC-SHA256 of "<timestamp>.<raw body>" with your app's webhook secret>).

app_id
string<uuid>
required

Your app's id.

app_name
string
required
error
object | null
required

Set when state is error, retryable, timed_out or discarded. error_type says where it failed: for a timed_out request it is timed_out, and for a discarded one discarded, unless the request was retryable when your app discarded it, which keeps the connection error that held it up. user_message is safe to show an end user; error_code is QuickBooks' own status code for a business error, hresult the Web Connector's for a connection/XML error; debug_message is for you.

id
string<uuid>
required

The request's id, as the 201 returned it. For an iterated query, every page carries the first page's id here.

page_request_id
string<uuid>
required

This page's own id. Equal to id except on later pages of an iterated query.

response_json
Success · object
required

QuBe Sync's summary of QuickBooks' answer. Only an Error severity from QuickBooks is status: "error" (and makes the request's state error), so a query that matched nothing is still success. A Warn severity is a success with warning beside it.

sandbox
boolean
required

Whether the app is a sandbox app.

state
enum<string>
required

response_received: QuickBooks accepted it; read response_json. error: it is over and QuBe Sync won't try again -- see error, and response_json.error for a QuickBooks business error; with error_type outcome_unknown a write may still have been applied, so look before sending it again. retryable: QuickBooks could not be reached and QuBe Sync keeps trying; show the customer error.user_message so they can fix it. timed_out: no answer came back -- the customer's computer lost its connection, or QuickBooks or the Web Connector was closed, mid-request. QuickBooks may still have applied it, so look before sending it again. discarded: your app discarded it before the Web Connector picked it up, so QuickBooks never got it. Both carry an error.

Available options:
response_received,
error,
retryable,
timed_out,
discarded
timestamp
integer
required

Unix seconds; the same t the signature covers.

iteration_state
enum<string>

continue: more pages will follow, each its own webhook. done: this was the last page. max_sandbox_iterations_reached: a sandbox app's page limit stopped the iteration.

Available options:
not_applicable,
continue,
done,
max_sandbox_iterations_reached

Present only with response_xml_omitted.

page
integer | null

The page number, when iterated.

response_xml
string | null

QuickBooks' raw qbXML answer. response_json is the same, summarized. One answer can be at most 4 MB as the Web Connector sends it, about 3 MB of qbXML; QuickBooks' answer over that isn't kept: this is null and error.error_type is response_too_large. A webhook whose body would be over 1 MB is sent without it: null, with response_xml_omitted true; fetch it from links.self.

response_xml_omitted
boolean

Present, and true, only when response_xml was left out to keep the body under 1 MB. response_json is still here; GET links.self for response_xml.

Response

2XX

Received. Anything else is retried with backoff for about 8 hours.

Response

Queued for the connection's Web Connector. Pass webhook_url and QuBe Sync POSTs the answer to it once QuickBooks has answered (see the answered callback: its own payload, not this document). links.self returns this document on demand, with response_json filled in.

data
object
required