When you program using the Desktop SDK, you will be accessing QuickBooks accounts, payments, credits, vendors, invoices, purchase orders, and so on. In the SDK documentation, we call these QuickBooks entities QuickBooks objects. This page covers how instances of these objects are identified and how you use the identifiers in query requests, modification requests, etc..
QuickBooks objects are categorized either as list objects or transaction objects. One of the first things you must do, when determining how to access some QuickBooks functionality via the SDK, is to determine whether you are dealing with a list or with a transaction, since the identifiers used for each of type is different.
For a full list of the QuickBooks objects and operations supported by the SDK, see QuickBooks objects and operations accessible with the SDK.
Note
Note
There are a few miscellaneous objects that are neither lists nor transactions—namely, company, host, preferences, and reports. These can be queried.
Identifiers are used to refer to list and transaction objects. Request and response messages specify the object identifiers by their identifiers. Also, within the QuickBooks database the object identifiers are used in object references to identify related objects. For example, an invoice typically has references to vendors, customers, etc.
List objects have two types of identifiers:
Transactions also have two types of identifiers:
TxnID is assigned by QuickBooks and does not change.When you are programming with the SDK you normally go the API Reference in order to see how to build request messages. A quick way to determine whether the object you are working with is a list object or a transaction object is to look at the response message for the object. List objects have a ListID at the beginning of the ret object; transaction objects have a TxnID in the beginning of their ret objects.
The following table contains functional groupings of the list objects that are supported by the SDK. These functional groupings are important because the object in a functional group have common behaviors. For example, if you know how to work with customer objects, which are in the entity group, then you will find that working with vendor objects, which are also in the entity group, is very similar. If you have sample code for customers, you should be able to readily adapt it to operate on vendors.
| Entity Lists | Item Lists |
|
|
| Customer and Vendor Profile Lists | Other Lists |
|
|
| Account Lists | |
|
* Premier Edition and Above ** Contractor, Professsional Services, Accountant flavors of Premier and above |
As mentioned above, listIDs are assigned by QuickBooks at the time an object instance is created. ListIDs will be unique within one of the groups shown in the following table:
| Entity Lists | Item Lists |
|
|
| Terms Lists | Payroll Item Lists |
|
|
For example, a customer instance will never have the same ListID as a vendor instance.
For the following types of objects, the list IDs need not be unique because each list is separate:
Notice that you can assign a name to a list object instance when you create or modify it. However, only QuickBooks can assign the ListID and that ListID cannot be changed. However, in some circumstances QuickBooks may appear to cause a ListID change. How? Suppose you have a customer that has job information, and you attempt to add a job to the customer.
From the QuickBooks UI, you can split the job information stored in the customer record, which effectively creates a NEW customer record, populates it with the non-job data of the original customer, and makes the original customer record with job data a child of that new record. Consequently, because the customer record is new, it will have a new ListID, but the same name. This will make it seem as though the ListID of that customer has changed. (The old customer ListID in this example is now referencing the customer job!)
Notice that you can do the same thing from the SDK when you get an error in trying to add a job to a customer, using the same logic.
As mentioned above, one of the object identifiers for list objects is fullname. To use the fullname effectively, you’ll need to now how it is constructed. This means understanding object names and object hierarchies.
Some list objects can have associated sub-objects—for example, a customer can have a number of jobs associated with the same customer. The relationship between a list object and its sub-object is described as a parent-child relationship. Examples of hierarchical list objects are customer and job, job and subjob, account and subaccount, and class and subclass.
The objects that can belong to hierarchical lists are listed below. The hierarchies for these objects can have up to four levels of children.
For these object types the full name can serve to locate specific instances by following the correct path through the hierarchy. For example, a contracting business might have multiple jobs named, “drywall installation,” or “framing,” and a fullname constructed from customer name and job name is needed to identify a specific instance.
For object instances that are not in hierarchies, the fullname is simply the instance name.
For object instances that are in hierarchies, it is necessary to include the sequence of parent-to-child relationships that form a path to the object instance, therefore, for these object instances, the fullname, much like a file path, concatenates the names of the parents and the instance to form a unique identifier. Within one of these fullnames, each name is delimited with a colon:
Brian Cook:Home:Kitchen:Sink
To summarize all of the above:
When you send a request to modify a list object, the request can fail if the object is currently being edited in the QuickBooks UI, or if the object was modified since the time you queried it from QuickBooks. If this failure occurs, you can handle it by querying QuickBooks to get the object again, in its current state, and then apply the modifications to the current copy.
The following table lists the invoiced transactions for a customer named Kristy Abercrombie. They cover work on various construction-related jobs, which are identified in hierarchical fullnames, that consist of customer name: job name: sub-job name. Each fullname must be unique, but notice that that the child names, the job and sub-job names do not need to be unique, since they are qualified by their parent names to form unique fullnames.
| FullName | Invoice # | Description |
|---|---|---|
| Kristy Abercrombie | Invoice #6 | Permits |
| Kristy Abercrombie:Bathroom | Invoice #1 | Demolition |
| Kristy Abercrombie:Bathroom:Floor | Invoice #2 | Tile |
| Kristy Abercrombie:Bathroom:Floor | Invoice #4 | Install |
| Kristy Abercrombie:Bathroom:Tub | Invoice #3 | Tub install |
| Kristy Abercrombie:Bathroom:Sink | .Invoice #5 | Reimbursement |
| Kristy Abercrombie:Kitchen | Invoice #7 | General |
| Kristy Abercrombie:Kitchen:Floor | Invoice #8 | Tile |
Suppose you construct an invoice query that includes this fullname tag:
<FullName>Kristy Abercrombie:Bathroom</FullName>
The response to this query will contain Invoice #1.
The following table shows other possible fullnames you could use in an invoice query the corresponding invoices that would included in the responses:
| If you perform an invoice query for… | This invoice is returned… |
|---|---|
| <FullName>Kristy Abercrombie:Bathroom</FullName> | Invoice #1 |
| <FullName>Kristy Abercrombie</FullName> | Invoice #6 |
| <FullName>Kristy Abercrombie:Bathroom:Sink</FullName> | Invoice #5 |
Entity, account, and item query requests also provide a FullNameWithChildren filter that can be useful when working with object hierarchies. For example, if you supplied the following:
<FullNameWithChildren>Kristy Abercrombie</FullNameWithChildren>
the response would include information for Kristy Abercrombie as well as the child jobs of this customer, which in this case would be all of the invoices listed above, because they are all children of Kristy Abercrombie. Other possible uses of FullNameWithChildren and the invoices that would be included in the respones, are listed below:
| If you perform an invoice query for … | This invoice is returned … |
|---|---|
| <FullNameWithChildren>Kristy Abercrombie:Bathroom<FullNameWithChildren> | Invoices #1, 2, 3, 4, 5 |
| <FullNameWithChildren>Kristy Abercrombie:Bathroom:Sink<FullNameWithChildren> | Invoice #5 |
ListID query messages have an analogous element: ListIDWithChildren. ListIDWithChildren includes the parent object as well as all of its descendants, just as FullNameWithChildren does.
When a hierarchical object is returned by QuickBooks, the response indicates the sublevel of the object, which is a number indicating how many parents the object has. The sublevel is returned in any Add, Modify, and Query response.
Many messages allow you to specify either the ListID or the FullName for an object. Because ListIDs cannot be changed, it is always safest to specify the ListID. If you specify both a ListID and a FullName for an object, QuickBooks looks only at the ListID. The
FullName is completely ignored in this case, even if the ListID cannot be found. (Note: This behavior applies to all Add and Mod requests.)
An object reference is used within an object instance (which can be either a list type or a transaction type) to point to a list object. An object reference contains a ListID and a FullName. Object references are used for two primary purposes:
The name of the object reference implies the type of object referred to. For example, a VendorTypeRef reference refers to a specific VendorType list object. A SalesRepEntityRef refers to a specific SalesRep. An ExpenseAccountRef refers to a specific account of type Expense, and so on.
In general, if you want to add or modify an object that contains an object reference, the referenced object must already exist in QuickBooks. However, the referenced object can be defined in an Add request in the same message set as the referring object. In this case, the referring object must come after the referenced object, and it must use a FullName as the reference if the referring object is a list object. (Transaction objects can use either FullName or macros.) For more information on macros, see Requests that define and use macros.”
Currently, the epoch is defined as the year 2038. You must specify DateTimes that fall on or before the epoch, as DateTimes after the epoch are invalid.
You can query for templates using the TemplateQueryRq to obtain the names of all templates that have been defined in QuickBooks. Templates are mainly used for specifying how to print certain transactions. The following transactions can have templates defined for them: credit memo, estimate, invoice, purchase order, sales order, and sales receipt.
Templates have an important correlation to custom fields: a transaction needs to reference a customized template that has custom fields turned on in order for a custom field to be displayed or printed. By default, custom fields are not turned on (and are therefore not displayed or printed by default either).
QuickBooks transactions reflect the flow of money into and out of a business. The following table lists functional groupings of the QuickBooks transaction objects that are supported in the SDK. Although you can assign a reference number to some transactions, QuickBooks always assigns a transaction IDto a transaction when it is created, and this ID cannot be modified.
Accounts Receivable General Journal Charge JournalEntry CreditCardRefund Check CreditMemo Invoice ReceivePayment Accounts Payable Deposit Bill SalesReceipt BillPaymentCheck BillPaymentCreditCard ItemReceipt Time-Tracking SalesTaxPaymentCheck TimeTracking VendorCredit Accounts Receivable Credit Card CreditCardCharge CreditCardCredit Non-posting Estimate PurchaseOrder SalesOrder (US Premier Edition and above) |
General Journal JournalEntry Check Bank and Sales Receipt Check Deposit Sales Receipt Time-Tracking TimeTracking General Journal Other InventoryAdjustment BuildAssembly (US Premier Edition and above) VehicleMileage |
The SDK supports the following operations:
The following example is a minimal version of the AccountAdd request message, which adds an account. It includes two required elements (Name and AccountType ) and one optional element (BankNumber). For optional elements that are left unspecified (such as AccountNumber and OpenBalance, in this case) QuickBooks will assume default values, if defaults exist. Elements that don’t have defaults are left blank.
<AccountAddRq requestID = "423">
<AccountAdd>
<Name>Checking Account</Name>
<AccountType>Bank</AccountType>
<BankNumber>0350039560</BankNumber>
</AccountAdd>
</AccountAddRq>
The response to an AccountAddRq is named AccountAddRs. The AccountAddRs response contains an AccountRet object. An AccountRet object is also returned when an account object is modified (AccountModRq).
After QuickBooks has successfully added the object, it returns a response message containing the AccountRet object. In this object, QuickBooks adds some elements, including the ListID, the time the object was created in QuickBooks (TimeCreated), the time the object was last modified (TimeModified), and a value representing the version of the object (EditSequence), plus some default values. The following example shows the AccountAddRs sent in response to the AccountAddRq message shown above.
<AccountAddRs requestID = "423"
statusCode = "0"
statusSeverity = "Info"
statusMessage = "Status OK">
<AccountRet>
<ListID>60000-933272656</ListID>
<TimeCreated>2001-02-19T13:54:39-08:00</TimeCreated>
<TimeModified>2001-02-19T13:54:39-08:00</TimeModified>
<EditSequence>933272656</</EditSequence>
<Name>Checking Account</Name>
<FullName>Checking Account</FullName>
<IsActive>true</IsActive>
<Sublevel>0</Sublevel>
<AccountType>Bank</AccountType>
<BankNumber>0350039560</BankNumber>
</AccountRet>
</AccountAddRs>
A request can specify an optional request ID, which can be used by your application to match up requests you send to QuickBooks with the responses it returns to you. This attribute is returned unchanged from QuickBooks in the matching response. Listing 13-1 specifies the optional ID, and Listing 13-2 returns it. The request ID can be very helpful in error recovery if you don’t use QBFC. (See Chapter 31, “Error Recovery.”)
The AccountRet and CustomerRet objects contain two elements, Balance and TotalBalance, which have different meanings. Balance refers to an amount that applies only to a specific element. In the table of invoices that appears above, for example, the subjobs Floor, Sink, and Bathroom, each have individual balances. TotalBalance is a cumulative total that is the sum of all subjob balances in a job (or, more generally, of descendants of a given parent object). In the following table, TotalBalance for Kitchen is $800 ($500 for floor and $300 for sink). The TotalBalance for KristyAbercrombie is the Kitchen TotalBalance ($800) plus the Bathroom TotalBalance ($400), or $1200.
| Job | Balance | TotalBalance |
|---|---|---|
| Kristy Abercrombie | 0.00 | 1200.00 |
| Kitchen | 0.00 | 800.00 |
| Floor | 500.00 | 500.00 |
| Sink | 300.00 | 300.00 |
| Bathroom | 400.00 | 400.00 |
A query request enables an application to obtain objects of a certain type or group of types and according to certain criteria from QuickBooks. The SDK defines a Query request for each type of list object and transaction object. Filters allow you to specify selection criteria for particular characteristics and parameters of the objects returned.
When a query specifies multiple filters, QuickBooks ANDs the filters and returns all objects that satisfy the criteria of all the filters specified.
Some query requests have no filters, such as the HostQueryRq, CompanyQueryRq, and PreferencesQueryRq.
HostQuery Request
QBXMLRP2, then using the QBXMLVersionsForSession call invoked against the request processor would be a better choice.)
In response, QuickBooks returns a HostRet object containing the following information (see the API Reference for details):
For detailed information on queries and filters, see Chapter 8, “Creating Queries.” For detailed information on reports, see Chapter 9, “Generating Reports.”
Attribute details are covered in the individual message reference pages. This section provides some background information.
There are several general types of attributes that are available:
We’ll describe each of these in the following sections.
There are several attributes related to how QuickBooks responds to errors in processing requests sent by your application.
These are message set-level attributes governing how the message set is to processed. For example, the onError attribute specifies how to proceed with subsequent requests in a message set if an error occurs. The newMessageSetID and oldMessageSetID instruct QuickBooks to save processing information in its state until you are sure your request and its response have been successfully processed. The responseData attribute specifies how much of the response to include.
onError Attribute
responseData Attribute
The responseData attribute can have a value of includeAll (the default) or includeNone. Note that if a response is returned without data, it might be because of an error, or it might be the result of the setting for this attribute.
Attributes for Error Recovery
If your application modifies data in the QuickBooks company file, you need to include the error recovery attributes in your request messages:
The messageSetStatusCode attribute will be in the response message if error-recovery attributes were included in the message set request. It provides the status of the entire request message that was set in the QBXMLMsgsRq request.
For a complete discussion of the use of the oldMessageSetID and newMessageSetID attributes and how to implement an error recovery routine in your application, see Error Recovery. These attributes allow you to instruct QuickBooks to save state concerning processing of the request, to check the processing status of a given request, and to clear state for a given request when you are sure that you’re finished processing the response. Also see the error recovery example included with the QuickBooks SDK Samples.
For requests that are not queries, there is one optional attribute, requestID. This attribute is used in requests in message sets where there are more than one request. The request ID allows you to match up requests and responses (the response to a request will have the same requestID) when you receive them in the response message set. This is important, because the order of requests submitted in the request message set might not be the order of responses coming back in the response message set.
Notice that if you use QBFC, you don’t have to deal with requestIDs. QBFC automatically assigns the requestID to the requests inside the message set, and guarantees that the order of responses returned matches the order of the requests submitted.
Every response contains three types of status information:
In addition to the general request and response attributes listed above, queries have several other attributes. These generally are intended to help you manage the amount of query data returned.
Query Request Attributes
These are attributes found in the query request
Query Response Attributes
For details on the query attributes, see Query requests and responses.