Query requests and responses

The SDK’s message set includes a number of messages designed for building queries. The queries have names like ItemInventoryQuery and SalesReceiptQuery and the corresponding QBFC request objects have names like ItemInventoryRQ and SalesReceiptQueryRQ. Your applications can use these request types to send requests for data about objects in the company file.

SDK queries support two ways to go about requesting object data:

• If the specific object is known, the application will already possess a unique identifier for the object (for list objects, this will be a listID or a fullname; for transaction objects, this will be a transactionID or a reference number), and it adds these identifiers to the query request and sends the request. Some of the conditions in which an application can use this approach are: the end user supplies the unique identifier, or the application displays a summary list of objects, including their unique identifiers, and the end user selects one to see a detailed view. As long as the identifiers are valid, the response will contain the specified objects.
• If the application does not possess a unique identifier, or if the need is to search by criteria, the application can set up one or more filters to request a set of of objects. Some of the conditions in which an application will take this approach are: the purpose of the query is to investigate what happened in a particular time period, or in a particular account, or to search for a specific object when its unique identifier isn’t known. The QBFC class or qbXML message for the query will support defining the filters, and the response will include any objects that meet the filtering criteria.

For a list of the QuickBooks object types for which the SDK supports queries, see Objects and operations supported by the SDK.

For a general discussion of sending requests, see Preparing and sending requests. For a general discussion of processing responses, see Receiving and processing responses.

Queries and reports both retrieve data from QuickBooks company files, but they have somewhat different uses. Query requests return sets of QuickBooks objects, of a specified object type, that meet whatever criteria your application includes in the query request. The fact that the data is received in the form of objects allows the application to perform further operations on the data or order the data for display as it sees fit. Report requests return formatted rows and columns, the data may include derived or calculated values, and the data can cover multiple object types.

There are often a number of ways to request and use a set of data. Depending on how you want to work with the returned data, one way of requesting it may be more effective than the others. For example, suppose you wanted to find customers having unpaid balances. The most effective way to request this data would be determined by how you want to work with it:

• If your goal is to write collection letters to these customers, you need their names and addresses. A CustomerQueryRq that specified a TotalBalance greater than zero would return a list of customer objects, which include this information, which your application could extract and insert info a form letter.
• If your goal is to create statements for these customers, you could use an InvoiceQueryRq and specify a PaidStatus of NotPaidOnly.
• A Collections Report, which is a type of AgingReportQueryRq, returns the same set of data, but in report form rather than in the form of QuickBooks objects.

When your application needs to request data, consider the possible ways of requesting it, and choose the most effective request.

The reports that can be requested by the SDK are listed in Reports that can be requested with the SDK. Requesting a report is covered in Preparing report requests.

In conditions where the application possesses unique identifiers for the objects it wants to request, the identifiers are added to the query as follows:

For list object queries, the application can actually supply both listIDs and fullnames without receiving an error, but the fullnames will be ignored.

The following is an example of a customer query request that specifies some customer objects with a set of customer ListIDs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

 <QBXML>
    <QBXMLMsgsRq onError = "continueOnError">
       <CustomerQueryRq requestID = "101">
          <ListID>150000-933272658</ListID>
          <ListID>160000-933272658</ListID>
          <ListID>180000-933272658</ListID>
          <ListID>940000-1071506775</ListID>
          <ListID>950000-1071506823</ListID>
       </CustomerQueryRq>
    </QBXMLMsgsRq>
 </QBXML>

The next example is a customer query request that specifies a FullName as the search criterion in a request for any and all customer objects for the purchase of an AirRow transporter by the customer named DaVinci.

1
2
3

 <CustomerQueryRq requestID = "591">
    <FullName>DaVinci:AirRow</FullName>
 </CustomerQueryRq>

For more information on lists, listIDs, and fullnames, see Objects, objectRefs, fullnames, and attributes.

When the goal is to obtain a set of objects that match some search criteria, the key part of preparing a query request is choosing the appropriate filters and then setting filter selection values that will return the desired set of objects. The SDK provides a set of filters which are listed in the following table. As shown in the table, some filters are specific to list queries, others to transaction queries, and some available in both kinds of queries. Each individual query has its own subset of these filters, appropriate for the type of object it queries. To see the filters available for any particular query, look the query up in the API reference. This page shows you how to use the filters provided by the SDK.

For list objects, you can optionally request that each object in the response also contain the Data Extension values for one or more Owner IDs. For more information, see Data Extensions: custom fields and private data.

Effective filtering is often the result of combining several filters. A number of the examples on this page show combinations of filters, such as combining, in a transaction query, an account type filter and a date range filter to narrow the results set to exactly the objects wanted. However, not all filters can be used together.

When preparing a query, check the API Reference to see which filters are available and which of them can be combined. The reference page for a query will show all the filters available, and use “or” statements to indicate which are mutually exclusive. For example, the API reference for the SalesTaxCodeQuery shows this information:

Among the filters available with this query there are two “or” relationships.

• The first “or” shows a choice between supplying a unique identifier and a using filter–the options are ListIDList, FullNameList, or ListFilter, which is an aggregate containing all of the available filters.
• The second “or” shows a choice, within ListFilter, between the Namefilter and the NameRangeFilter–the query supports both, but not at the same time.

The AccountFilter filter allows you to filter for transactions associated with a specified account or list of accounts. The accounts can be specified by a nested sub-filter, one of:

• ListID
• FullName
• ListIDWithChildren
• FullNameWithChildren

Be sure that the accounts you specify can actually have transactions of the type you are requesting. If you are preparing an InvoiceQueryRq, for example, the specified accounts must be Accounts Receivable type accounts or there is no possible way any transactions can be found and returned!

Also, when preparing your queries, keep in mind that this filter operates on the top-level accounts associated with transactions. For invoices, for example, the top-level accounts are A/R accounts and for bills they are A/P accounts. Now suppose you have an invoice for the A/R account “My AR Account” that includes a line item, and the funds from that line item are accounted for in an income account called “Sales.” Specifying “Sales” in the account filter will not return that invoice—in fact, such a filter can’t return any invoices because “Sales” is not an A/R account. However, If you specified the account “My AR Account” in the account filter, the invoice would be returned (assuming the invoice was not excluded by any of the other filters in the request).

The following example combines the AccountFilter and the TxnDateRangeFilter to request any invoice objects for the AccountsReceivable:SportingGoods account that were created during the last month.

1
2
3
4
5
6
7
8

 <InvoiceQueryRq requestID = "73">
    <TxnDateRangeFilter>
       <DateMacro>LastMonth</DateMacro>
    </TxnDateRangeFilter>
    <AccountFilter>
       <FullName>AccountsReceivable:SportingGoods</FullName>
    </AccountFilter>
 </InvoiceQueryRq>

The AccountType filter (only available with an AccountQueryRq request type) allows the application to filter an account query so that it returns only accounts the specified type or types. Account type is an enumerated value from the following list:

• atAccountsPayable
• atAccountsReceivable
• atBank
• atCostOfGoodsSold
• atCreditCard
• atEquity
• atExpense
• atFixedAsset
• atIncome
• atLongTermLiability
• atNonPosting
• atOtherAsset
• atOtherCurrentAsset
• atOtherCurrentLiability
• atOtherExpense
• atOtherIncome

The ActiveStatus filter allows you to filter for list objects that have the specified status. The filter takes enumerated values of:

• asActiveOnly
• asInactiveOnly
• asAll

The default value is asActiveOnly, so to prepare a request that will return inactive objects you need to change the value.

The DateMacro filter allows you to specify a date range in a date range-type filter, without supplying “from” and “to” dates You instead supply one of the following date macros, which specify a date range relative to the current date.

• All
• Today
• ThisWeek
• ThisWeekToDate
• ThisMonth
• ThisMonthToDate
• ThisCalendarQuarter
• ThisCalendarQuarterToDate
• ThisFiscalQuarter
• ThisFiscalQuarterToDate
• ThisCalendarYear
• ThisCalendarYearToDate
• ThisFiscalYear
• ThisFiscalYearToDate
• Yesterday
• LastWeek
• LastWeekToDate
• LastMonth
• LastMonthToDate
• LastCalendarQuarter
• LastCalendarQuarterToDate
• LastFiscalQuarter
• LastFiscalQuarterToDate
• LastCalendarYear
• LastCalendarYearToDate
• LastFiscalYear
• LastFiscalYearToDate
• NextWeek
• NextFourWeeks
• NextMonth
• NextCalendarQuarter
• NextCalendarYear
• NextFiscalQuarter
• NextFiscalYear

Queries for ToDo lists allow you to specify a DoneStatus filter for the elements to be returned. You can specify NotDoneOnly(the default), DoneOnly, or All.

A “to do”list is used in QuickBooks to keep track of tasks. Notice that the various Name filters refer to the Notes field in the ToDoQuery. So, by using these filters, you are searching the Notes.

The EntityFilter filter allows you to filter for transactions that are associated with one or more entities. Entity filters can be used, for example, to request a set of payments by a specified customer or a set of bills received from a specified set of vendors.

The entity filter allows you to specify the entity or entities with one of the following nested filters:

• ListID
• FullName
• FullNameWithChildren
• ListIDWithChildren

The following example shows an example of an invoice query that combines a date range filter and an entity filter. This request asks QuickBooks to return all invoices pertaining to the Jones’s kitchen that were modified between January 2 and January 5, 2002.

1
2
3
4
5
6
7
8
9

 <InvoiceQueryRq requestID = "73">
    <ModifiedDateRangeFilter>
       <FromModifiedDate>2002-01-02</FromModifiedDate>
       <ToModifiedDate>2002-01-05</ToModifiedDate>
    </ModifiedDateRangeFilter>
    <EntityFilter>
       <FullName>Jones:Kitchen</FullName>
    </EntityFilter>
 </InvoiceQueryRq>

The next example combines a ModifiedDateRange filter and an EntityFilter to request all bills from an entity (the company’s landlord, New World Real Estate for rent on all of the company’s San Jose offices), from January 01, 2003, through March 31, 2003.

1
2
3
4
5
6
7
8
9

 <BillQueryRq requestID = "81">
    <ModifiedDateRangeFilter>
       <FromModifiedDate>2003-01-01</FromModifiedDate>
       <ToModifiedDate>2003-03-31</ToModifiedDate>
    </ModifiedDateRangeFilter>
    <EntityFilter>
       <FullNameWithChildren>NewWorldRealEstate:rent:SanJoseOffices</FullNameWithChildren>
    </EntityFilter>
 </BillQueryRq>

Using the FullNameWithChildren filter as a nested sub-filter allows you to fully define an AccountFilter, Entityfilter, or CurrencyFilter, by specifying the account, entity, currency, etc., to be used in the query request. It is possible to specify part of a fullname “path,” in order to request related objects that may be descendants of the partial path. For example, an invoice query specifying customer:job would respond with any and all invoices associated with that customer and job combination.

For more information on fullnames, inlcuding examples of fullname paths, see Objects, objectRefs, fullnames, and attributes.

A line item is a line that adds detail to a transaction object such as an invoice or a bill. By default, the value of this flag is false and transaction queries will not return any line items. To include line items in the response, specify true.

A linked transaction is a transaction that is associated with the original transaction in some way. For example, a credit memo could be linked to a customer invoice, thereby adding credit to a customer’s account. By default, the value of this flag is false and transaction queries will not return any linked transactions. To include linked transactions in the response, specify true. For more information about linked transactions, see Requests that link: item receipts and bills to purchase orders, invoices to sales orders.

The default behavior for a query response is to return all of the objects the meet the filtering criteria specified in the request and all of the properties of the returned objects. IncludeRetElement allows you to specify which properties are returned, in order to limit the size of the response message set to only the data the application needs.

To use IncludeRetElement, specify the name of a top-level data element or aggregate that the application will be working with:

• You cannot specify nested elements within an aggregate. For example, you cannot specify City, which is within Address; you must specify Address and the response set will contain the entire address.
• If the application will be working with data contained in multiple elements or aggregates, use a separate IncludeRetElement for each of them.
• The object property name (or qbXML tag name) you specify is not parsed, and no error is returned in the status code if you specify an invalid tag name so be careful to supply a valid name, spelled and cased correctly.

The following sample customer query shows the IncludeRetElement tag in use, in a customer query, to limit the data returned to the fullname property:

<?xml version="1.0"?>
<?qbxml version="4.0"?>
<QBXML>
  <QBXMLMsgsRq onError="continueOnError">
    <CustomerQueryRq requestID="2">
      <IncludeRetElement>FullName</IncludeRetElement>
    </CustomerQueryRq>
  </QBXMLMsgsRq>
</QBXML>

The response to this query looks like the following:

<?xml version="1.0" ?>
<QBXML>
  <QBXMLMsgsRs>
    <CustomerQueryRs requestID="2" statusCode="0" statusSeverity="Info" statusMessage="Status OK">
      <CustomerRet>
        <FullName>Abercrombie, Kristy</FullName>
      </CustomerRet>
      <CustomerRet>
        <FullName>Abercrombie, Kristy:Family Room</FullName>
      </CustomerRet>
      ......more customer names.......
    </CustomerQueryRs>
  </QBXMLMsgsRs>
</QBXML>

This page covers the use of IncludeRetElement in queries. Note that it is also available in Add and Mod requests, where it will limit the data in the responses to those requests.

Beginning in SDK 4.0, IncludeRetElement has made it possible for an integrated application to send a EmployeeQueryRq query that is limited to properties of the EmployeeRet object that do not require “Payroll and Employees” permissions. Such a query will execute and return the unrestricted data, such as Name, even if the logged in user lacks “Payroll and Employees” permissions.

Using the ListIDWithChildren filter as a nested sub-filter allows you to fully define an AccountFilter, Entityfilter, CurrencyFilter, by specifying the account, entity, currency, etc., to be used in the query request. It is possible to specify part of a ListID”path,” in order to request related objects that may be descendants of the partial path. For example, an invoice query specifying customer:job would respond with any and all invoices associated with that customer and job combination.

For more information on ListIDs, see Objects, objectRefs, fullnames, and attributes.

Using the MatchCriterion filter as part of a NameFilter or a RefNameFilter allows you use the query as a wildcard query on a partial name. MatchCriterion takes enumerated values of

• mcStartsWith
• mcContains
• mcEndsWith

The ModifiedDateRange filter allows you to filter for objects that were modified within the specified range of dates. The filter provides two ways to specify the date range: supplying “from” and “to” dates, and using date macros.

Using FromModifiedDate and/or ToModifiedDate in a query request allows you to filter for objects that were modified within the specified range of dates. You can specify a range, with “from” and “to” dates, a “from” date only, or a “to” date only. The following example shows a customer query request that combines the ActiveStatus, FromModifiedDate, and ToModifiedDate to filter for customer objects that are currently active and were modified at any time between the beginning of day on October 12, 2003, and end of day on October 15, 2003:

1
2
3
4
5
6
7

 <CustomerQueryRq requestID = "541">
    <ActiveStatus>asActiveOnly</ActiveStatus>
    <ModifiedDateRangeFilter>
       <FromModifiedDate>2003-10-12</FromModifiedDate>
       <ToModifiedDate>2003-10-15</ToModifiedDate>
    </ModifiedDateRangeFilter>
 </CustomerQueryRq>

Dates used with these filters are of type DATETIMETYPE, which specifies both the date and the time up to the second. If you don’t specify a full date, down to the second, the SDK will interpret the supplied date according to the following rules. These tables list the values assigned by the SDK when the application supplies less than a full date. The first covers the “from” date.

The next covers the “to” date.

When a time zone is not specified, local time is assumed.

The allowable range of dates for the FromModifiedDate and ToModifiedDate filters changed from SDK version 1.1 to version 2.0.

• For version 2.0 and above, the range is from 1970-01-01 to 2038-01-19T03:14:07 (2038-01-18T19:14:07-08:00 PST).
• For versions 1.1 and 1.0, the range is different for list objects and transaction objects:
  • For list objects, the range is from 1970-01-01 and 2038-01-19T03:14:07 (2038-01- 18T19:14:07-08:00 PST).
  • For transaction objects in versions 1.1 and 1.0, the range is from 01/01/1901 to 12/31/ 9999.

In some queries, the modified date filter supports specifying the date range with a date macro as an alternative to the “from” and “to” dates. For details, see Using_the_DateMacro_filter.

Using the NameFilter, you can filter for objects with names that match a supplied string. You specify both the string itself (which can be all or part of a FullName) and the MatchCriterion, which can be StartsWith, Contains, or EndsWith. For example, you could use it in a customer query to request all customers whose names start with “Mac.” Or you could use it in a customer query to request all objects that contain “kitchen” as part of their full name.

The example shows an item inventory query that asks for all items with the word bolt in their name. The filter is case-insensitive.

1
2
3
4
5
6

   <ItemInventoryQueryRq requestID = "795944”/>
    <NameFilter>
       <MatchCriterion>Contains</MatchCriterion>
       <Name>bolt</Name>
    </NameFilter>
 </ItemInventoryQueryRq>

Using the NameRangeFilter in a request allows you to filter for list objects with names that fall within a range of names. The scale for names in QuickBooks runs from 0 to 9 and then from A to Z. Using this filter, you can specify starting and ending points anywhere along that scale. You scan specify both the beginning and ending strings in a range, the starting string only, or the ending string only. If you specify both FromName and ToName are specified, FromName must precede ToName on the scale. String values for names are case-insensitive. In a sorted list, punctuation characters are first, followed by numeric characters, and then alphabetical characters.

The PaidStatus filter allows you to filter for invoices or bills with the specified paid status. You can specify the enlumerated values:

• PaidOnly – filters for bills or invoices that are completely paid (that is, closed)
• NotPaidOnly – filters for bills or invoices that have a non-zero balance

You will probably not bother specifying All for this filter, since that is the equivalent of not specifying the filter.

The RefNumberFilter allows you to filter for objects with reference numbers that match a specified string. You specify both the string itself (which can be all or part of a reference number) and the MatchCriterion, which can be StartsWith, Contains, or EndsWith. For example, you could use this filter with a invoice query and request all invoices whose reference numbers start with “00.”

The RefNumberRangeFilter allows you to filter for objects with reference numbers that fall within a range. You can specify the starting and ending points of the range, the starting point only, or the ending point only.

Transactions without reference numbers are ignored by queries that use the RefNumberFilter and queries that use the RefNumberRangeFilter with both “From” and “To” values specified. However, if the RefNumberRangeFilter is used with only a “To” value or only a “From” value, QuickBooks returns the transactions that have no reference numbers.

Using RefNumberCaseSensitive Instead of RefNumber

Prior to QuickBooks 2006, if the reference number contained letters, not just numeric digits, RefNumber could be very slow. The RefNumberCaseSensitive tag was provided for this case to improve performance. However, starting with QuickBooks 2006, RefNumber and RefNumberCaseSensitive provide the same good performance. The RefNumberCaseSensitive tag can be used if case sensitivity is desired, however.

The TotalBalance filter in a CustomerQueryRq or VendorQueryRq request (the only request types that support this filter), you can filter for customers or vendors with the specified balance. The filter allows you to specify an amount and one of the following operators:

• LessThan
• LessThanEqual
• Equal
• GreaterThan
• GreaterThanEqual

The returned objects are sorted by TotalBalance, For the operators LessThan, LessThanEqual, and Equal the sort is in ascending order (lowest to highest); for the operators GreaterThan and GreaterThanEqual, the sort is in descending order (highest to lowest).

Using the FromTxnDate and/or ToTxnDate filters in a query request allows you to filter for transaction objects that were dated within the specified range. You can specify a range, with “from” and “to” dates, a “from” date only, or a “to” date only. The following example shows a customer query request that combines the ActiveStatus, FromModifiedDate, and ToModifiedDate to filter for customer objects that are currently active and were modified at any time between the beginning of day on October 12, 2003, and end of day on October 15, 2003:

1
2
3
4
5
6

 <customerqueryrq requestid="541">
    <activestatus>asActiveOnly
    </activestatus>
    <fromtxndate>2003-10-12</fromtxndate>
    <totxndate>2003-10-15</totxndate>
 </customerqueryrq>

Dates used with these filters are of type DATETIMETYPE, which specifies both the date and the time up to the second. If you don’t specify a full date, down to the second, the SDK will interpret the supplied date according to the rules listed above in Using FromModifiedDate and ToModifiedDate.

In some queries, the modified date filter supports specifying the date range with a date macro as an alternative to the “from” and “to” dates. For details, see Using_the_DateMacro_filter.

The default behavior for a query response is to include all of the objects and data properties that meet the query’s filtering criteria. This can lead to large response message sets. The SDK provides ways to limit by object count how much data is returned for a request: Requests can be repeated to return data that was not in the first response message set, and the effect is one of paging though the objects that meet the query’s filtering criteria:

• Using the MaxReturned element in a query limits the number of objects returned in the response message set.
• Using an iterator in a query limits the number of objects returned in a response message set and provides an index that allows the application to page through the results by a specified number of objects in each (This feature is available only in Desktop editions QB 2006 and later using qbXML spec 5.0 and greater.)

The best way is to use the iterator feature, which is specific to queries. The second way is to use the IncludeRetElement feature, which is a feature common to nearly all qbXML requests, not just queries.

In some situations, you may want to get a count of the objects that would be returned from a specific query you have prepared before actually running the query, in order to determine whether you have a reason to use MaxReturned or an iterator to manage the size of the response message set, or if you want to allocate enough memory.

Queries have an attribute called metaData, which can be set so that no objects are returned in the query, just an approximate count of how many objects would be returned. MetaData has the following values:

• MetaDataOnly – include only the object count in the response message
• NoMetaData – do not include the object count in the response message
• MetaDataAndResponseData – include the object count and the actual objects in the response message

Note that the count returned by a query with metadata is approximate, because other users can add or delete objects between the time the application queries for the count and the time it queries for the objects.

Many query types include the MaxReturned element, which allows you to specify the maximum number of objects that will be returned in each response message set. If your application deals with large amounts of data, using MaxReturned can help you ensure acceptable application performance.

If your query uses both filters and MaxReturned, the filters are applied first and then the MaxReturned value is applied to the set of objects resulting from the filter. The application is responsible for managing the “paging,” by keeping track of the last object returned and then specifying the starting point of the next request. Use the following procedure:

1. Issue a query request (for example, a CustomerQueryRq) with a MaxReturned element that specifies a reasonable amount of data (for example, 100). This first query does not include a From/To specification, it simply returns a response message set with the first 100 objects.
2. To continue looking at objects that match the query’s criteria, issue another query of the same type (in this example, another CustomerQueryRq request) and specify the starting point for the next results message set. For example, if you are dealing with an alphabetized list of customer names, use NameRangeFilter:FromName and specify the last object returned in the previous response message set. You do not need to specify the NameRangeFilter:ToName, MaxReturned will determine the number of objects returned in the response.

The iterator attribute, which is available with most query types (check the API Reference pages for availability in specific queries), also allows you to break down query results in smaller and more manageable chunks of data. An iterator results in responses that contain only the specified number of objects. Iterators are only valid for the application that starts them, and they are only valid for the current QuickBooks session. (Once the current QuickBooks session ends, or QuickBooks is shut down, all the iterators go away.)

Starting an iterator preloads the set of things that are going to be returned to you and gives you the specified number (MaxReturn) that you requested in each iteration. However, the iterator does not remember all aspects of your query (just the filters!). Accordingly, if you use other fields in the query, such as IncludeRetElement, then you have to repeat those in each continuation of the iterated query! This feature is available only to desktop editions QB 2006 and later using qbXML spec 5.0 and greater.

To start an iterator set the query’s iterator attribute set to Start and set an appropriate value for MaxReturn. The response to this query includes:

• The first set of response objects, up to the value specified in MaxReturn
• An IteratorID, which uniquely identifies the iterator that was started. The application will use this to identify the iterator in follow-up query requests. Note that an application can have multiple iterators active at the same time, if it does it will use their IDs to identify them.

The following example shows a request that starts an iteration:

1
2
3
4
5
6
7
8

 <qbxml>
    <qbxmlmsgsrq onerror="stopOnError">
       <customerqueryrq iterator="Start" requestid="5001">
          <maxreturned>10</maxreturned>
          <includeretelement>ListID</includeretelement>
       </customerqueryrq>
    </qbxmlmsgsrq>
 </qbxml>

The response contains the returned objects, with the iteration-related information returned in the response attributes, as shown in the following snippet:

1
2
3
4
5

 <customerqueryrs iteratorid="{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}"
                           iteratorremainingcount="50" requestid="5001" statuscode="0"
                           statusmessage="..." statusseverity="INFO">
       ...??
 </customerqueryrs>

In addition to the iteratorID, the query response includes an attribute called iteratorRemainingCount. This gives the number of remaining objects that meet the query criteria that were not returned in preceding iteration(s). As part of managing the paging, the application must check this value. When the value is 0:

• There are no more objects to be obtained by follow-up queries
• the Iterator is now removed from memory and its iteratorID is no longer valid. Therefore, further attempts to access it will fail.

Other than checking for a remaining count equal to 0, the application may find other uses for iteratorRemainingCount, such as evaluating it and possibly changing the query’s MaxReturned setting.

To continue an iteration, prepare a follow-up query request again, with the following changes:

• Set the Iterator attribute’s value to Continue.
• Set the IteratorID attribute to the IteratorID value returned to the initial query request.
• The iterator remembers the filters used in the initial query, but not other attributes, such as IncludeRetElement, If you used any of those in the initial query request they will need to be repeated in each follow-up query request.
• Once a query request that initiates an iterator has been sent, follow-up queries (queries using that same iteratorID and the iterator attribute set to Continue) cannot change any filtering specified in the initial query. The only thing the application can change during an iteration is the MaxReturned value.

The following is an example, in qbXML, of a follow-up query; it follows the example above:

1
2
3
4
5
6
7
8
9

 <qbxml>
    <qbxmlmsgsrq onerror="stopOnError">
       <customerqueryrq iterator="Continue" iteratorid="{D7355385-A17B-4f5d-B34D-F34C79C3E6FC}"
                                 requestid="5001">
          <maxreturned>10</maxreturned>
          <includeretelement>ListID</includeretelement>
       </customerqueryrq>
    </qbxmlmsgsrq>
 </qbxml>

At any point during an iteration, you can stop the iterator and destroy it (which frees up memory) by issuing a follow-up query request with the iteratorID set to the proper value and the Iterator attribute set to “Stop.” It is good practice to do this if you want to stop an iteration before reaching iteratorRemainingCount = 0, otherwise the iterator will continue to be held in memory until the current QuickBooks session ends, potentially occupying a large amount of memory. (If your application crashes before cleaning up its iterators, the iterators it was using can be removed from memory by restarting QuickBooks.)

Note that if the application completes the query (reaches iteratorRemainingCount = 0), you need not, and in fact cannot, issue the query with the iterator attribute set to “Stop,” because the iteratorID is no longer valid.

This section provides information concerning the AccountRet object, which is the detail object in an AccountQuery response.

Most QuickBooks accounts are created in response to an explicit request by the small business owner. “Special accounts” are accounts created automatically by QuickBooks for a special purpose, usually as a side-effect of creating some other transaction. The SpecialAccountType value is an enumerated type and is returned only if the queried account is a special account. Examples of special account types are AccountsPayable, AccountsReceivable, CostOfGoodsSold, SalesOrders, UncategorizedExpenses, and UndepositedFunds.

If QuickBooks needs to create one of its special accounts and the name it uses for this account type has already been used (because a manually created account was assigned the same name), QuickBooks prepends an asterisk (*) to the account name (for example, *UndepositedFunds).

The tax line information returned in the AccountRet response relates to the tax form the user selected for the company (for example, Form1120, Form1120S, Form1065). To determine what tax form the tax lines relate to, you can query the Company object and inspect the TaxForm field returned in the CompanyRet object.

The tax line information (TaxLineInfoRet) contains two elements:

• TaxLineID: an internal number used by QuickBooks to identify a particular line in the specified tax form
• TaxLineName: a descriptive name of the line on the specified tax form

If the user assigned a cash flow classification in QuickBooks, you can obtain the classification for a given account from the AccountRet object. The user assigns this value to an account in QuickBooks by selecting Preferences > Reports & Graphs > Company Preferences > Classify Cash. The SDK defines the following enumerated values for the CashFlowClassification element:

• Operating: corresponds to the Operating classification in QuickBooks
• Investing: corresponds to the Investing classification in QuickBooks
• Financing: corresponds to the Financing classification in QuickBooks
• NotApplicable: this account cannot be assigned a cash flow classification

Most queries are oriented to a specific object type. There are also a number of “special” queries:

• PreferencesQuery – allows you to check whether certain operations will be permitted before you attempt to perform them. This way, you can anticipate errors that would be returned by QuickBooks and take appropriate action ahead of time.
• HostQuery – returns information about the QuickBooks product and version as well as the versions of the qbXML specification.
• CompanyQuery – returns basic information about a QuickBooks company file
• CompanyActivityQuery – This query allows you to determine the date when the company file was last restored. If you receive Status Code 3240 (Time creation mismatch), you will need to identify the most up-to-date copy of the company file.
• BillToPayQuery – returns the transaction IDs for all open bills and credits.
• ReceivePaymentToDepositQuery – returns the transaction IDs for all customer payments that need to be deposited.

TransactionQuery is a query that provides functionality (e.g. filters) similar to the Advanced Find window in the QuickBooks UI. It allows you to search for transactions across different transaction types. In contrast to the other, type-specific transaction queries, which return all the attributes of one transaction type, the TransactionQuery returns only the data attributes that are common to all transaction types, such as TxnID, Type, Dates, accountRef, and so on.

If additional, more type-specific data is required, a follow-up request of the appropriate query type can be used to get that type-specific data. For example, the TransactionQuery can be used to present all transactions in a certain date range, then the user can select a particular transaction, say an invoice transaction. In response to this choice, the application could send an InvoiceQuery request to pull up all of the invoice data, similar to QuickZoom feature in the QuickBooks UI.

TimeTracking transactions are not supported in the generic TransactionQuery. (This mirrors the QuickBooks UI where TimeTracking transactions aren’t available in the Find functionality.)

QuickBooks access permissions are obeyed in the TransactionQuery. The behavior varies depending on how you use (or don’t use) the transaction type filter. If you set the transaction type filter to “All” (or if you don’t set it at all), the query searches only those transaction types that are permissible types for the user currently logged in. If instead of “all,” you specify a transaction type that the currently logged in user is not permitted to access, you get a runtime error, even if other permissible transaction types were specified as well.

Finally, the transaction type filter is subject to sensitive data access level restrictions and payroll subscription status.

The TransactionQuery has filters similar to those available for reports, although the filter names are special toTransactionQuery, including:

• TransactionFilter, where you can specify one or more specific transaction types or “All” types if you wish.
• TransactionDetailLevelFilter, where you can specify the detail level of the query results: all results, summary only (the default), or all except summary. (Summary only refers to the transaction as a whole, whereas all except summary refers to the transaction lines.)
• TransactionPostingStatusFilter, where you can specify transactions based on posting status. Valid values are posting, non-posting, or either (the default). (Posting status refers to whether QuickBooks records a transaction in one of your account registers.)

TransactionPaidStatusFilter, where you can search for “open” transactions, i.e. transactions with a remaining balance (for example, credits not fully applied or invoices not fully paid). Valid values are closed, open, or either (the default).