Batch Invoice Queries Fail When Any Single RefNumber Is Missing
Submitting multiple invoice numbers in a single QuickBooks query causes the entire batch to fail if even one number has no matching record in the company file.
A long-standing frustration for anyone building custom integrations with the QuickBooks desktop SDK is the way batch invoice lookups behave when one number in the set is invalid. A developer querying a list of invoice reference numbers — say, pulled from an external file — will find that a single unmatched number can torpedo the entire request, returning no usable data for the invoices that do exist.
The Problem in Practice
The scenario is common enough. A program reads a list of invoice numbers from a file, feeds them into a single query using the reference-number list feature, and expects QuickBooks to return the matching invoices one by one. The plan is to process the ones that come back and write the unmatched numbers to a separate file for review.
The snag is that QuickBooks does not handle a missing reference number gracefully inside a batch. If the list contains, for example, invoice “144” and invoice “9999,” and the second number does not exist in the company file, the entire query fails rather than returning partial results. The developer is left with nothing — no data for the valid invoice, no clean per-item error, and no straightforward way to separate the good numbers from the bad.
This is not a bug in the traditional sense. It is simply how the SDK processes a multi-item reference-number query: the request is treated as an all-or-nothing operation. When any element cannot be matched, the whole request is rejected.
Why the Obvious Setting Does Not Help
A natural first instinct is to adjust the error-handling behavior on the message set. The SDK exposes an “on error” attribute that can be set to “continue,” which sounds like exactly what is needed — tell QuickBooks to keep going when it hits a problem.
Unfortunately, that setting governs what happens across multiple distinct requests inside a single batch message, not across multiple values inside a single query. It will not rescue a reference-number list where one of the entries is missing. The query still fails as a unit.
The Accepted Fix: One Request per Invoice
The top-rated solution in the developer community is straightforward: stop putting multiple invoice numbers into a single query. Instead, submit each invoice number as its own individual request, all bundled into one message set. The “on error: continue” setting then does what its name suggests — if one individual request fails, the remaining requests still execute and return their data.
In practice, this means looping through the list of invoice numbers and adding a separate invoice query for each one, each containing a single reference number. When the message set is sent, QuickBooks processes every request independently and returns a response for each. The responses can then be examined one at a time.
Any response carrying a non-zero status code points to a problem with that specific invoice number. The program can log the number, write it to the “not found” file, and move on — all while still receiving full data for the invoices that do exist.
What to Watch For
A few practical notes emerge from the discussion:
Response count matches request count. Each individual request produces its own response, so the developer can iterate through them in order and correlate each response back to the original invoice number by position.
Status codes are the filtering mechanism. A successful lookup returns a status code of zero. Anything else signals that the invoice was not found or that another error occurred for that specific number.
Scalability is a consideration. Sending hundreds or thousands of individual requests in a single message set can work, but performance may degrade with very large batches. Developers working with high volumes may want to test chunk sizes and find a balance between throughput and reliability.
The Broader Takeaway
The reference-number list feature looks like a convenient way to fetch a batch of invoices in one shot, but it carries a hidden fragility. For any workflow where the input list may contain invalid or stale numbers — which is precisely the situation that prompts the lookup in the first place — the safer path is individual requests within a batch message. It trades a small amount of simplicity for a large amount of resilience, and it lets the program cleanly separate found from not-found without losing the data it came for.