Common Questions about qbXML Requests/Responses

General qbXML Questions

How much of the QuickBooks API is exposed via qbXML?

Almost all of it. Certain functions are not supported:

  • Payroll requests
  • Querying for voided transactions

What is an EditSequence value?

Exactly what it sounds like- it's a token that keeps track of the sequence of edits of a record.

Every time a record is modified (whether via the SDK, or via the QuickBooks GUI), the EditSequence changes.

When you submit a request to modify an object, you *must* specify the *latest* EditSequence value. This is QuickBooks' way of ensuring that you have first retrieved the latest revision of the record, before trying to update it.

How does qbXML handle special characters (accents, non-US/non-ASCII characters, etc.)?

This does not work: (it fails with a “QuickBooks found an error with the XML” error)

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="2.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
		<CustomerAddRq>
			<CustomerAdd>
				<Name>1234567 Steel Décor</Name>
				<CompanyName>Steel Décor</CompanyName>
				<FirstName>George</FirstName>
				<LastName>Jetson</LastName>
				<BillAddress>
					<Addr1>1210 E. Maple</Addr1>
					<City>Seattle</City>
					<State>WA</State>
					<PostalCode>12345</PostalCode>
					<Country>USA</Country>
				</BillAddress>
				<Phone>555-555-1212</Phone>
				<Fax>555-555-1212</Fax>
				<Contact>George Jetson</Contact>
			</CustomerAdd>
		</CustomerAddRq>
	</QBXMLMsgsRq>
</QBXML>

Here's an example of a correctly encoded request: (notice the encoded e with the accent symbol)

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="2.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
		<CustomerAddRq>
			<CustomerAdd>
				<Name>1234567 Steel D&#233;cor</Name>
				<CompanyName>Steel D&#233;cor</CompanyName>
				<FirstName>George</FirstName>
				<LastName>Jetson</LastName>
				<BillAddress>
					<Addr1>1210 E. Maple</Addr1>
					<City>Seattle</City>
					<State>WA</State>
					<PostalCode>12345</PostalCode>
					<Country>USA</Country>
				</BillAddress>
				<Phone>555-555-1212</Phone>
				<Fax>555-555-1212</Fax>
				<Contact>George Jetson</Contact>
			</CustomerAdd>
		</CustomerAddRq>
	</QBXMLMsgsRq>
</QBXML>

And here is the response we get back form QuickBooks:

<?xml version="1.0" encoding="utf-8"?>
<QBXML>
	<QBXMLMsgsRs>
		<CustomerQueryRs requestID="Q3VzdG9tZXJRdWVyeXxnZXQtbmV3LWN1c3RvbWVycw==" statusCode="0" statusSeverity="Info" statusMessage="Status OK">
			<CustomerRet>
				<ListID>800008E5-1256341725</ListID>
				<TimeCreated>2009-10-23T19:48:45-05:00</TimeCreated>
				<TimeModified>2009-10-26T19:01:27-05:00</TimeModified>
				<EditSequence>1256598087</EditSequence>
				<Name>1234567 Steel D&#233;cor</Name>
				<FullName>1234567 Steel D&#233;cor</FullName>
				<IsActive>true</IsActive>
				<Sublevel>0</Sublevel>
				<CompanyName>Steel D&#233;cor</CompanyName>
				<FirstName>George</FirstName>
				<MiddleName></MiddleName>
				<LastName>Jetson</LastName>
				<BillAddress>
					<Addr1>1210 E. Maple</Addr1>
					<City>Seattle</City>
					<State>WA</State>
					<PostalCode>12345</PostalCode>
					<Country>USA</Country>
				</BillAddress>
				<Phone>555-555-1212</Phone>
				<Fax>555-555-1212</Fax>
				<Contact>George Jetson</Contact>
				<Balance>0.00</Balance>
				<TotalBalance>0.00</TotalBalance>
				<JobStatus>None</JobStatus>
			</CustomerRet>
		</CustomerQueryRs>
	</QBXMLMsgsRs>
</QBXML>

Is there anything special about the Addr4 and Addr5 fields?

With qbXML, you have to use *either* Addr4 and Addr5 *OR* City, State, PostalCode, and Country. As long as the fields you use do not total to more than 5 address lines when printed in a standard address format, you'll be OK. If you try to use an address that would display as six address lines, the request will be rejected by QuickBooks.

i.e. This is valid:

...
<ShipAddress>
   <Addr1>56 Cowles Road</Addr1>
   <Addr2>Suite D</Addr2>
   <Addr3>Attn: Keith Palmer Jr.</Addr3>
   <City>Willington</City>
   <State>Connecticut</State>
   <PostalCode>06279</PostalCode>
   <Country>USA</Country>
</ShipAddress>
...

And this is valid:

...
<ShipAddress>
   <Addr1>56 Cowles Road</Addr1>
   <Addr2>Suite D</Addr2>
   <Addr3>Attn: Keith Palmer Jr.</Addr3>
   <Addr4>Willington, Connecticut 06279</Addr4>
   <Addr5>USA</Addr5>
</ShipAddress>
...

But this *is not valid* (because is uses Addr4 *and* the City, State, PostalCode, and Country fields):

...
<ShipAddress>
   <Addr1>56 Cowles Road</Addr1>
   <Addr2>Suite D</Addr2>
   <Addr3>Attn: Keith Palmer Jr.</Addr3>
   <Addr4>Ref: 1234</Addr4>
   <City>Willington</City>
   <State>Connecticut</State>
   <PostalCode>06279</PostalCode>
   <Country>USA</Country>
</ShipAddress>
...

Is there anything special about addresses in QuickBooks in general?

Yes, they are very strange. Here's an article from an Intuit developer about how QuickBooks stores addresses as of 2009:

Problem statement:
Goal is to create a QuickBooks customer for which we need to enter the country name in the Bill To address. When editing the Country/Region field on the Edit Address Information window, QuickBooks automatically moves certain country names (f.i. Albania, Croatia, etc.) from the Country/Region field to the Address field.

Answer:
QuickBooks stores addresses as a single string. It does not store address details in separate fields. QuickBooks relies on parsing to separate out the address details so whatever shows up in the “Address Detail” window is not guaranteed to appear in the same way again. This is why Croatia, or any other text string we don't have in our list of countries will not be recognized as such, and thus placed in the field that will be determined at run time by the parser. If this string is the only one in the given address, so, as the address is not a valid address, the parser just chose the city location. I've included the list of countries at the end of this email.

As you point out we cannot always keep up with an exhaustive list of countries to validate as well as the keep up with the parsing rules for each country so we focused on domestic and Canadian addresses which covers needs for the vast majority of our user base and has worked well for them over the past several releases.

This isn't a quick fix or workaround to this issue. Because we don't store the address details as separate fields we can't simply turn off the parsing behavior. The long term solution is to change our data structure in a future release so we store address details in separate fields. This would guarantee that the address details are represented correctly for all addresses as well as remove the "strange" things you describe in import and export.

List of Countries (note countries like USA are represented in multiple formats)
Argentina,
Australia,
Austria,
Bahrain,
Belarus,
Belgium,
Bolivia,
Brazil,
Brunei,
Brunei Darussalam,
Bulgaria,
Canada,
Chile,
China,
Colombia,
Costa Rica,
Czech,
Czech Republic,
Denmark,
Dominican Republic,
Ecuador,
Egypt,
England,
Estonia,
Finland,
France,
Germany,
Great Britain,
Greece,
Guatemala,
Holland,
Hong Kong,
Hungary,
Iceland,
India,
Indonesia,
Ireland,
Israel,
Italy,
Jamaica,
Japan,
Kenya,
Kuwait,
Latvia,
Liechtenstein,
Lithuania,
Luxembourg,
Macau,
Malaysia,
Mexico,
Monaco,
Morocco,
Netherlands,
New Zealand,
Nicaragua,
North Korea,
Norway,
Oman,
P.R.O.C.,
Pakistan,
Panama,
Paraguay,
Peru,
Philippines,
Poland,
Portugal,
PROC,
R.O.C.,
Republic of Korea,
ROC,
Romania,
Russia,
Saudi Arabia,
Scotland,
Singapore,
Slovak Republic,
Slovakia,
Slovenia,
South Africa,
South Korea,
Spain,
Sweden,
Switzerland,
Taiwan,
Thailand,
Turkey,
U.A.E.,
U.S.A.,
UAE,
UK,
Ukraine,
United Kingdom,
United States,
United States of America,
Uruguay,
US,
USA,
Venezuela,
Vietnam,
Wales


Developer Support Engineer
Intuit Developer Network 

What does "0x80040400 QuickBooks found an error when parsing the provided XML text stream." mean?

It means you have some sort of strange error in your qbXML request. Try running the your qbXML request through the QuickBooks qbXML test/validator utilities included in the QuickBooks SDK.

It's worth noting that order matters when building qbXML requests. For example, if the qbXML request is defined in the OSR like this:

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="7.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
		<CustomerAddRq>
			<CustomerAdd>
				<Name>STRTYPE</Name>
				<FirstName>STRTYPE</FirstName>
				<MiddleName>STRTYPE</MiddleName>
				<LastName>STRTYPE</LastName>
				...

Then this will not work (because the <Name>…</Name> and <FirstName>…</FirstName> tags are in the opposite order):

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="7.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
		<CustomerAddRq>
			<CustomerAdd>
				<FirstName>Keith</FirstName>				
				<Name>Keith R Palmer</Name>
				<MiddleName>R</MiddleName>
				<LastName>Palmer</LastName>
				...

Other common errors would include:

  • Leaving out required elements
  • Forgetting to close tags/really ugly, invalid XML streams
  • Sending non-ASCII or non-UTF-8 text (don't send strange, non-standard characters)
  • Sending XML attributes that should be escaped: & < >. These need to be converted to: &amp; &lt; &gt; to include them in qbXML requests.

Questions about Customers

How can I get a list of deleted customers?

You can use the

ListDeletedQuery

query to fetch a list of deleted Customers (and other deleted object types).

Questions about Invoices

How can I set the invoice number for an invoice?

You can set the invoice number for an invoice by setting the

<RefNumber>...</RefNumber>

tag in your qbXML InvoiceAddRq or InvoiceModRq. The returned TxnID tag is auto-generated by QuickBooks and cannot be set, but the RefNumber will be the one displayed in the QuickBooks GUI.

If you don't specify a RefNumber, QuickBooks will try to guess the next RefNumber based on the last previously created invoices' RefNumber field. (i.e. if the last invoice you added had a RefNumber of “5” then QuickBooks will assign the next invoice a RefNumber of “6” if you don't specify otherwise.)

How can I get a list of deleted invoices?

You can get a list of deleted invoices (and other transactions) by using the

TxnDeletedQuery

method. Here is some example qbXML:

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="7.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
		<TxnDeletedQueryRq>
			<!-- TxnDelType may have one of the following values: ARRefundCreditCard, Bill, BillPaymentCheck, BillPaymentCreditCard, BuildAssembly, Charge, Check, CreditCardCharge, CreditCardCredit, CreditMemo, Deposit, Estimate, InventoryAdjustment, Invoice, ItemReceipt, JournalEntry, PayrollLiabilityAdjustment [PRIVATE], PayrollPriorPayment [PRIVATE], PayrollYearToDateAdjustment [PRIVATE], PurchaseOrder, ReceivePayment, SalesOrder, SalesReceipt, SalesTaxPaymentCheck, TimeTracking, VehicleMileage, VendorCredit -->
			<TxnDelType>...</TxnDelType> <!-- required, may repeat -->
			<DeletedDateRangeFilter> <!-- optional -->
				<FromDeletedDate>DATETIMETYPE</FromDeletedDate> <!-- optional -->
				<ToDeletedDate>DATETIMETYPE</ToDeletedDate> <!-- optional -->
			</DeletedDateRangeFilter>
		</TxnDeletedQueryRq>
	</QBXMLMsgsRq>
</QBXML>

How can I send more than one request at once?

You can chain requests together to send more than one request at once. Here's an example:

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="7.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">

		<CustomerAddRq requestID="Q3VzdG9tZXJBZGR8MTExMTIxMjE=">
			<CustomerAdd>
				<Name>Keith Palmer Jr.</Name>
				<FirstName>Keith</FirstName>
				<MiddleName></MiddleName>
				<LastName>Palmer Jr.</LastName>
				<BillAddress>
					<Addr1>134 Stonemill Road</Addr1>
					<City>Mansfield</City>
					<State>CT</State>
					<PostalCode>06268</PostalCode>
					<Country>USA</Country>
				</BillAddress>
				<Phone>999-99-9999</Phone>
				<Email>test@example.com</Email>
				<Contact>Keith Palmer Jr.</Contact>
			</CustomerAdd>
		</CustomerAddRq>
		
		<DataExtModRq>
			<DataExtMod>
				<OwnerID>0</OwnerID>
				<DataExtName>CustomerNumber</DataExtName>
				<ListDataExtType>Customer</ListDataExtType>
				<ListObjRef>
						<FullName>Keith Palmer Jr.</FullName>
				</ListObjRef>
				<DataExtValue>1234</DataExtValue>
			</DataExtMod>
		</DataExtModRq>
		
	</QBXMLMsgsRq>
</QBXML>

Here's another example, this one adds two items with a single qbXML request.

<?xml version="1.0" encoding="utf-8"?>
<?qbxml version="6.0"?>
<QBXML>
	<QBXMLMsgsRq onError="stopOnError">
	
		<ItemNonInventoryAddRq requestID="1">
			<ItemNonInventoryAdd>
				<Name>Test Item 1</Name>
				<IsActive>true</IsActive>
				<SalesOrPurchase>
					<Desc>Test Item 1 Description</Desc>
					<Price>15.00</Price>
					<AccountRef>
						<FullName>Sales</FullName>
					</AccountRef>
				</SalesOrPurchase>
			</ItemNonInventoryAdd>
		</ItemNonInventoryAddRq>
		
		<ItemNonInventoryAddRq requestID="2">
			<ItemNonInventoryAdd>
				<Name>Test Item 2</Name>
				<IsActive>true</IsActive>
				<SalesOrPurchase>
					<Desc>Test Item 2 Description</Desc>
					<Price>25.00</Price>
					<AccountRef>
						<FullName>Sales</FullName>
					</AccountRef>
				</SalesOrPurchase>
			</ItemNonInventoryAdd>
		</ItemNonInventoryAddRq>
	
	</QBXMLMsgsRq>
</QBXML> 

essay writing service

quickbooks_qbxml_questions.txt · Last modified: 2013/01/21 12:44 (external edit)