Skip to content

IDs, SyncToken & sparse updates ​

Cross-cutting rules that apply to every live entity. You usually don't need to change application code for these — they're listed so you know what's happening and why behavior matches QuickBooks Online.

IDs ​

We pass Desktop's ListID / TxnID through as the QBO Id. As long as your code doesn't parse the format of an ID (almost nobody does), references work unchanged across create → read → update → delete.

CompanyInfo is the exception: its Id equals the Company ID (Desktop's company profile has no ListID/TxnID). See the CompanyInfo section.

SyncToken ​

Maps to Desktop's EditSequence. Optimistic-concurrency conflicts return the same 400 you'd get from QBO when the token is stale — re-fetch and retry.

ReferenceType ​

QBO's { value, name } shape maps to Desktop's ListID + FullName. Either side of a round-trip keeps both pieces when Desktop returns them.

Updates & sparse updates ​

Updates (?operation=update, or a POST body with Id) are classified by the body, not just the query param: a POST whose body carries an Id is always treated as an update, whether or not ?operation=update is on the URL — an Id-bearing POST never reaches create, so it can never duplicate the record.

?operation=update — or a body with "sparse": true — with no Id can't be an update, so we fail loud with a 400 instead of guessing.

Desktop has no partial update, so we read-merge-write the full record for you. Your sparse POST behaves like QBO's — with one semantic difference worth knowing: every update behaves as sparse on Desktop, whether or not your request sets "sparse": true. QBO's full update clears any writable field you omit from the body; Desktop's Mod has no "clear what's missing" mode, so omitted fields are always preserved, never cleared — even on a full-body update with no sparse flag. If your client relies on QBO's full-update semantics to blank out a field by omitting it, that won't happen here; set the field explicitly instead.

Line-level updates ​

On Invoice, Estimate, SalesReceipt, CreditMemo, PurchaseOrder, JournalEntry, Deposit, Bill, VendorCredit, Purchase (Check, CreditCardCharge and CreditCardCredit) and InventoryAdjustment, an update that carries Line is the complete new line table, the same contract as QBO:

  • Keep a line by sending its Id (the Line.Id a read returned). Desktop keeps the line's identity, so line Ids stay stable across updates and links that point at a specific line survive. Fields you omit on a line that carries an Id are merged from the current record.
  • A line with no Id is added.
  • A line you leave out is deleted. To leave the lines untouched, omit Line entirely; header-only updates never touch lines. An empty Line: [] is rejected (2020) rather than deleting every line.
  • The same Id twice in one array is a 2010 fault; an Id that is not on the record is a 400.

Entity notes: a JournalEntry update is checked for balance over the merged lines and a line may flip between Debit and Credit. On a Deposit, a payment-linked line keeps its link but its amount and payer come from the payment, so edits to them are not applied. A CashBack that changes the current one is sent as a single change to the cash back; posting the record back with its CashBack unchanged sends nothing, and CashBack: null removes it. Adding cash back to a deposit that has none is refused (422). On a PurchaseOrder, changing Qty or UnitPrice without Amount recomputes Amount.

On Bill, VendorCredit and Purchase a line cannot change type: sending an expense line's Id with an item detail (or the reverse) is a 2010 fault, so omit the Id to replace the line. An item line that sends Amount without Qty or UnitPrice keeps its quantity and gets a new unit cost, so the Amount you send is the one you read back. A Purchase keeps its family: PaymentType (and Credit) cannot change on update, and a Check cannot become a CreditCard purchase (2010; delete and re-create).

A BillPayment (Check family) takes the same contract on its applications: Line is the whole set, keyed by the bill (LinkedTxn[0].TxnId). A bill you leave out is unapplied and reopens, and the payment total recomputes. A vendor credit already applied through the payment stays applied if a later update omits it. Credit-card bill payments cannot be updated (UNSUPPORTED_BY_DESKTOP); delete and re-create them.

CustomerMemo and TxnTaxDetail.TxnTaxCodeRef are also updatable on the four sales forms. Line-level updates on other transaction entities still fail loud with UNSUPPORTED_BY_DESKTOP.

Deletes ​

POST /{entity}?operation=delete works for transactions (Invoice, SalesReceipt, Bill, Payment, TimeActivity, Estimate) and returns QBO's {"status": "Deleted"} shape.

One honesty note: Desktop's delete takes no SyncToken, so a stale token can't be rejected the way QBO would. Name-list entities (Customer, Vendor, Account, Item) are never deleted — matching QBO, deactivate them with a sparse Active: false update.

Item types ​

QuickBooks Desktop has many more item types than QBO. Every one of them reads through the Item API, in get-by-id and in query results, with the nearest QBO Type and a read-only DesktopItemType: assemblies read as Inventory, fixed assets as NonInventory, and other-charge, discount, subtotal, payment, sales tax and sales tax group items as Service. So a sync that lists items and then fetches every item an invoice line references never gets a 422.

DesktopItemType is also how you write the families QBO has no Type for: Discount, OtherCharge, Subtotal, Payment, InventoryAssembly and FixedAsset. Groups are written with Type: "Group" and QBO's bundle shape, ItemGroupDetail.ItemGroupLine[{ItemRef, Qty}]; assemblies use ItemAssemblyDetail.ItemAssemblyLine the same way. On update, sending the component array replaces the whole list, so read the item, change what you need and post every line back; an update that leaves the array out (a rename, for example) keeps the components. A DesktopItemType that disagrees with Type, or that changes on update, is a 400 with code 2010. Sales tax and sales tax group items cannot be written through the Item API: write a sales tax item through the TaxRate endpoint (POST /taxrate) and a sales tax group through POST /taxservice/taxcode. A fixed asset item is written with Type: "NonInventory", DesktopItemType: "FixedAsset", a PurchaseDate, a PurchaseDesc (or Description) and an AssetAccountRef, plus the optional PurchaseCost, AcquiredAs (New or Old), VendorOrPayeeName, Location and SerialNumber. See the Item compatibility entry.

Cleared status ​

QuickBooks Desktop keeps a cleared status (the "Clr" column of a register) on the bank, credit card or other balance sheet side of a transaction. QuickBooks Online has no API for it, so this is a TenkeyBridge extension:

  • Set it: POST /v3/company/{companyId}/clearedstatus with {"TxnId": "<Id>", "LineId": "<Line.Id>", "ClearedStatus": "Cleared"}. ClearedStatus is Cleared, NotCleared or Pending (Reconciled is QuickBooks' own and cannot be written). LineId is optional. The answer is {"ClearedStatus": {"TxnId", "LineId"?, "ClearedStatus"}, "time"}.
  • Read it back: GET /v3/company/{companyId}/clearedstatus?txnid=<Id>&txntype=Purchase answers in the same envelope, {"ClearedStatus": {"TxnId", "TxnType", "TxnDate", "Splits": [...]}, "time"}, with one split per bank or balance sheet posting, each with Role, a LineId you can send back, its ClearedStatus, Amount and SetByTxnId on the split a request without a LineId would change. It costs one extra QuickBooks read of the transaction's own accounts on its own date; it is never a whole-file query, and ordinary entity reads carry no cleared status and cost nothing extra.

Which side a request sets (live-proven on QuickBooks Enterprise 24, txntype in the first column):

TransactionTxnId alone setsLineId sets
Purchase (check)the check's bank account (AccountRef)that line's account, when it is a balance sheet account (for example a check line posted to a savings or clearing account)
Depositthe deposit-to account (DepositToAccountRef)that deposit line's source account, when it is a balance sheet account
BillPayment (check)the bank accountno lines: a LineId is 610
JournalEntrythe first line only (refused when that line is not on a balance sheet account)that line's account
Transferrefusedrefused

So to tick only a clearing account and leave Checking alone, put the clearing account on a line (a deposit line or a check line, or a journal entry line) and send that line's LineId; a request without LineId on a deposit or check sets the deposit-to or bank side instead. QuickBooks keeps one status per posting, so the two sides of a transaction are independent.

  • A line posted to an income, expense, cost of goods, A/R or A/P account has no cleared status in QuickBooks: 422 UNSUPPORTED_BY_DESKTOP.
  • A transfer cannot be cleared through the API: QuickBooks refuses a transfer id for either side (422 UNSUPPORTED_BY_DESKTOP, also before anything is sent when you pass TxnType: "Transfer"). Its status can still be read back. Record the movement as a deposit or journal entry if the API must clear it.
  • Setting the same status twice is accepted (a no-op). A transaction dated in a closed period is refused by QuickBooks; that refusal is passed through as a 422 naming the closing date (not reproduced live: qbXML cannot set a closing date).
  • The read-back accepts a txndate parameter and ignores it: the gateway reads the transaction first, which gives it the date that bounds the ledger read.
  • Setting a status does not change the transaction's SyncToken, so it never conflicts with an edit.
  • requestid works as on any write, and since the call is a set, repeating it is harmless. After a lost response, send TxnType with the request: the gateway can then settle the outcome with a read (applied when every addressed split already shows the status), otherwise it answers 502 REQUEST_OUTCOME_UNKNOWN.

The npm client has client.setClearedStatus() and client.getClearedStatus(), and the MCP server has the set_cleared_status and get_cleared_status tools. See the ClearedStatus compatibility entry.

Projects ​

QuickBooks Online has projects; QuickBooks Desktop has jobs. A job is a customer under a parent customer, and a QBO project is a sub-customer with IsProject: true, so the two map one to one.

  • Create a project: POST /customer with {"DisplayName": "Roof Repair", "IsProject": true, "ParentRef": {"value": "<customer Id>"}}. IsProject: true needs a ParentRef (without one the answer is 400 code 2020); IsProject: false together with a ParentRef is 400 code 2010. Nothing extra is sent to QuickBooks: the parent is what makes the customer a job.
  • Read and query: every customer under a parent reads IsProject: true (and Job: true). select * from Customer where IsProject = true returns them.
  • Transactions: ProjectRef on an Invoice, Estimate, SalesReceipt or CreditMemo sets the customer to the project. If CustomerRef is also sent, the project wins. On read, a transaction whose customer is a job returns ProjectRef with the same value and name as CustomerRef; CustomerRef is never rewritten to the parent.
  • Difference from QBO: a Desktop job can sit under another job, so a project here means any Desktop job. QBO projects are one level deep.

Examples use the fictional ExampleCo company and Pat Owner.

Email and print status ​

EmailStatus and PrintStatus on the sales forms map to QuickBooks' "to be emailed" and "to be printed" queues. NeedToSend and NeedToPrint queue the form; NotSet, EmailSent and PrintComplete clear it. A read returns NeedToSend / NeedToPrint for a queued form and NotSet otherwise: Desktop does not record that a form was sent or printed, so EmailSent and PrintComplete are never returned. Setting a status sends nothing by itself.

PDF and send ​

GET /{entity}/{id}/pdf always answers 422 UNSUPPORTED_BY_DESKTOP: qbXML cannot render or return a PDF of a transaction, and TenkeyBridge does not render one. Build the PDF from the JSON record in your own application.

POST /{entity}/{id}/send works on Invoice, Estimate, SalesReceipt and CreditMemo. It is a thin wrapper over a sparse update that sets EmailStatus: NeedToSend, so the form lands in QuickBooks' "To be e-mailed" queue and the updated record is returned. TenkeyBridge does not send mail; someone (or QuickBooks' own Send Forms) has to send the queued form from Desktop, to the customer's email address. QuickBooks refuses the queue (3180) when the company file has no valid company email. The optional sendTo parameter is ignored (a Desktop form has no address of its own, like BillEmail), and the response carries an X-TKB-Warning saying so. Other entities answer 422.

Estimates have no "to be printed" queue in QuickBooks Desktop, so an Estimate takes EmailStatus only. PrintStatus: NotSet (the QBO default) is accepted and ignored; any other value is refused with UNSUPPORTED_BY_DESKTOP.

BillEmail, BillEmailCc and BillEmailBcc are accepted and dropped: a Desktop form has no email address of its own, and QuickBooks uses the customer's. Change PrimaryEmailAddr on the customer to change where forms go. ApplyTaxAfterDiscount is supported: Desktop decides line by line, from each discount line's tax code, so true codes the discount lines Tax (tax after the discount) and false codes them Non (tax on the full amount). Set DiscountLineDetail.TaxCodeRef on a line to choose its code directly.

Name lookups ​

QuickBooks Desktop does not say which name list a name belongs to. A time entry or a journal entry line carries only the name, so a read asks QuickBooks which list owns it (Customer, Vendor or Employee) to fill TimeActivity.NameOf and JournalEntry line Entity.Type. That is one extra QuickBooks round trip on those reads, about a second over the Web Connector, and the answer is cached per company file for 15 minutes. If the lookup fails, a time entry read is refused with NAME_LOOKUP_FAILED rather than guessing the kind, and a journal entry line comes back without Type. A journal entry write answers without Entity.Type; read the entry to see it.

Voids ​

POST /{entity}?operation=void with {"Id": "...", "SyncToken": "..."} voids a posted transaction and returns the record as Desktop reports it afterwards. Supported for Invoice, SalesReceipt, Purchase (Check, CreditCardCharge and CreditCardCredit families) and BillPayment (check and credit-card families). QuickBooks Desktop can also void a Bill, VendorCredit, Deposit, JournalEntry, InventoryAdjustment and CreditMemo; QBO cannot, so these are TenkeyBridge extensions on the same call (a QBO client never sends them, so nothing changes for existing code). Under the hood: a read (finds the Desktop family and the current EditSequence), a TxnVoidRq, then a re-read.

  • SyncToken is enforced. Desktop's TxnVoidRq has no EditSequence input, so TenkeyBridge compares your SyncToken to the record's current EditSequence before voiding and returns 5010 Stale Object Error on a mismatch — the same as QBO. SyncToken is required.
  • Residual race window. TxnVoidRq takes no EditSequence, so a change made in QuickBooks between our read and the void is not detected; the SyncToken check protects against stale callers, not against that gap.
  • Unknown read-back. If the void succeeds but the follow-up read fails, you get 502 VOID_APPLIED_READBACK_FAILED — the void was applied; GET the record and do not retry.
  • Payment cannot be voided. qbXML has no void for ReceivePayment; the call returns 400 UNSUPPORTED_BY_DESKTOP — delete the payment instead. Every other entity also returns 400.
  • Batch: operation: "update" + optionsData: "void" (Batch guide).
  • What Desktop returns after a void (proven on QuickBooks Enterprise 24): the same Id and TxnDate, totals and line amounts at 0, and PrivateNote prefixed VOID: . Invoice and SalesReceipt lines also get Qty: 0; a BillPayment's applied-to-bill Line entries disappear and the bills it paid reopen. Voiding an already-voided record succeeds and changes no amounts. A void does not reliably advance the SyncToken, so re-read the record instead of relying on it.
  • The extension voids (proven on QuickBooks Enterprise 24): a Bill, VendorCredit, Deposit or InventoryAdjustment gets PrivateNote prefixed VOID: , and its totals and line amounts go to 0.00 with the lines kept. A voided Bill reads Balance: 0.00 (Desktop marks it paid). A voided JournalEntry has every line at 0.00 and VOID: before the memo of its first line only; Desktop returns both lines on the debit side, so do not expect per-line debit and credit sides on a voided journal entry. Voiding an InventoryAdjustment reverses its stock effect. A void does not reliably advance the SyncToken, so re-read the record instead of building on it.
  • Voiding a check adds journal entries. When you void a Purchase of the Check family, QuickBooks posts a journal entry dated the check's own date that re-books the original check, and a reversing journal entry dated the day of the void, and rewrites the memo to VOID: <memo> GJE, RGJE created on MM/DD/YYYY (the void date). A check voided in a later month therefore still shows its expense in the original month, and the reversal lands in the month of the void. The check is also marked printed (PrintStatus: PrintComplete). Expect those two entries in the bank register and journal reports. Credit-card charge and credit voids are not yet live-tested.
  • Sandbox: the sandbox reproduces this post-void shape, memo included, but does not create the journal-entry pair.

Warnings ​

A request can succeed and still carry a caveat. Non-fatal conditions come back on the successful response in an X-TKB-Warning header (printable ASCII, at most 500 characters, several warnings joined with ; ). The body is unchanged, so clients that ignore the header keep working. You will see it in two cases:

  • QuickBooks warned. Desktop performed the request but answered with a warning-severity status for part of it. The header reads QuickBooks warning <code>: <message>, for example QuickBooks warning 530: The field "Name" is not supported by this implementation. (Employee DisplayName no longer takes this path: Desktop derives it from the first, middle and last names, so a write naming a different one is refused with a 400 up front.)
  • TenkeyBridge ignored a field. On an Invoice, SalesReceipt, Estimate or CreditMemo create or update, a TxnTaxDetail.TotalTax sent without a TxnTaxCodeRef is not sent to QuickBooks, which computes the tax itself. If its figure differs from yours the header reads TxnTaxDetail.TotalTax ignored; QuickBooks Desktop computed 8.25.

Warnings appear on single-record and query responses, never on error responses, and the TotalTax warning is not emitted for /batch items. See Warnings in the error reference.

Query support ​

GET /v3/company/{companyId}/query?query=... accepts QBO's SQL-like language:

sql
SELECT * | COUNT(*) | Col1, Col2, ... FROM Entity
  [WHERE cond AND cond ...]
  [ORDERBY field [ASC|DESC] [, field ...]]      -- ORDER BY also accepted
  [STARTPOSITION n] [MAXRESULTS n]

A cond is field = | != | < | > | <= | >= value, field IN ('a','b'), or field LIKE 'pattern' (% is the only wildcard). Keywords are case-insensitive; strings are single-quoted with \' and \\ escapes; numbers and true/false are bare (quoted numbers are accepted too, as QBO does). Like QBO, there is no OR.

sql
select * from Customer where DisplayName = 'Acme'
select * from Invoice where CustomerRef = '12' and TxnDate >= '2026-01-01'
  and TxnDate <= '2026-03-31' orderby TxnDate desc maxresults 100
select count(*) from Invoice where Balance > '0'
select * from Item where Name like 'Wid%'
select Id, DisplayName from Customer where Id in ('1', '2')
  • Page size is capped at 500. QBO allows MAXRESULTS up to 1000; TenkeyBridge caps it at 500 to protect the Desktop instance. A larger value is not refused: you get at most 500 rows and an X-TKB-Warning header (MAXRESULTS 1000 reduced to 500; ...). QueryResponse.maxResults is the number of rows returned, as in QBO. Page by advancing STARTPOSITION by the rows you received (or until an empty page), never by comparing the row count to the MAXRESULTS you asked for: a client that stops at "fewer rows than I asked for" would stop after 500 and miss the rest.
  • minorversion is accepted on every route and ignored. TenkeyBridge always answers in one shape, whatever number you send.
  • COUNT(*) answers { "QueryResponse": { "totalCount": N } } (count of the filtered set; STARTPOSITION/MAXRESULTS are ignored).
  • Column lists return exactly the listed properties (Id is not added implicitly; dotted names such as MetaData.LastUpdatedTime keep their nesting).
  • ORDERBY sorts the whole filtered set before STARTPOSITION/MAXRESULTS slice it. Strings sort case-insensitively, dates and timestamps chronologically, amounts numerically; a record with no value sorts first (last when descending).
  • String comparisons (=, !=, IN, LIKE, <, …) are case-insensitive and trimmed — a TenkeyBridge rule, not a verified match of QBO's own collation. Refs (CustomerRef = '12') compare the exact id.
  • A date-only value against a timestamp (MetaData.LastUpdatedTime >= '2026-06-01') names the whole UTC day: >= starts at its first instant, <= runs through its last, >/< exclude it. Strict < / > on TxnDate become inclusive bounds one day over.

What QuickBooks filters, and what TenkeyBridge filters ​

QuickBooks Desktop can only apply some conditions itself. TenkeyBridge pushes every condition it can into the qbXML request and applies the rest to the translated records before sorting, counting and paging. The gateway-side path fetches up to 5,000 records from QuickBooks; if that fetch comes back full it returns UNSUPPORTED_QUERY (never a possibly-incomplete answer) — narrow the query with a pushed filter.

EntityApplied by QuickBooks (fast)
All transactions — Invoice, SalesReceipt, Estimate, CreditMemo, Payment, RefundReceipt, Bill, VendorCredit, PurchaseOrder, BillPayment, Purchase, JournalEntry, Deposit, Transfer, TimeActivityId (=, IN); TxnDate and MetaData.LastUpdatedTime with =, <, <=, >, >= (both bounds together); DocNumber = / IN and one-sided LIKE ('INV%', '%24', '%2026%') — not TimeActivity, which has no reference number in Desktop; on Payment the field is PaymentRefNum (DocNumber is accepted as an alias)
Invoice, Estimate, SalesReceipt, CreditMemo, Payment, RefundReceiptCustomerRef (=, IN)
Bill, VendorCredit, PurchaseOrder, BillPaymentVendorRef (=, IN)
PurchaseEntityRef — the payee (=, IN)
Invoice, BillBalance > 0 narrows to unpaid documents in QuickBooks; the exact test runs gateway-side
All lists — Customer, Vendor, Employee, Account, Item, Class, Term, PaymentMethod, CustomerType, TaxCode, TaxRate, CompanyCurrency, ExchangeRateId (=, IN); Active (=, !=, IN (true, false)); MetaData.LastUpdatedTime ranges; the entity's name (DisplayName on Customer / Vendor / Employee, Name elsewhere) with = and LIKE
Customer, Account, Class, ItemFullyQualifiedName = / IN ('Acme:Kitchen'). On these hierarchical lists QuickBooks matches names against the full colon path, so a name = or prefix LIKE narrows the fetch and is then checked exactly on the short name — DisplayName = 'Kitchen' finds the job Acme:Kitchen
TaxAgencyActive only (it is derived from several Desktop lists)

Everything else — MetaData.CreateTime, != and IN on dates, numeric comparisons (TotalAmt, Balance, …), any other field (PrimaryEmailAddr, CompanyName, GivenName, AccountType, SalesTermRef, …), interior-wildcard LIKE — is applied by TenkeyBridge to the fetched records. Conditions combine with AND only. Id, DocNumber and FullyQualifiedName lookups are single QuickBooks requests that take no other filter, so any other condition in the same query is checked on the (tiny) result.

Timestamps and MetaData.LastUpdatedTime. QuickBooks Desktop rejects any datetime ending in Z, so TenkeyBridge sends explicit +00:00 offsets (full datetimes are honored to the second). Desktop reads a date-only bound in the machine's local time, and labels every timestamp it returns with a fixed -07:00 while its clock is local — so the MetaData times you read can be an hour off true UTC during daylight saving. A date-only LastUpdatedTime bound is therefore pushed a day wider each way and then re-checked against the returned MetaData (the UTC-day rule above), while a full datetime bound is pushed exactly and trusted as sent.

Other details. IN lists are de-duplicated and may hold at most 1,000 distinct values (4000 above that). String literals may not contain control characters (4000). Unquoted ISO dates and words (TxnDate >= 2026-01-01, DocNumber = INV-100) are still accepted as strings, as before. ORDERBY Id compares all-digit ids numerically. A name equality (DisplayName = 'Acme') narrows the Desktop fetch with a NameFilter; if that returns nothing the gateway retries once over the unfiltered list before answering empty, names containing non-ASCII characters are never pushed, and setting TKB_QUERY_NAME_PUSHDOWN=off on the gateway disables name pushdown entirely (full scan + exact check, as before v2). Name LIKE always keeps its exact gateway-side re-check.

Two-phase scan. When a WHERE or ORDERBY can't be pushed into QuickBooks, the gateway no longer pulls full records for the whole scan window. It first asks QuickBooks for just the id, EditSequence and the few fields the query reads (IncludeRetElement; no line items, linked transactions or custom fields), filters, sorts and pages those slim rows, then fetches the full records for only the returned page by id (in chunks of 250). Results are identical to a single full fetch; COUNT(*) and column lists the slim rows already cover need no second request, and an empty page stops after the first. It applies to Customer, Vendor, Account, Class, Invoice, Bill, SalesReceipt, Estimate and CreditMemo; other entities, conditions on a property the slim request can't express (for example Bill.Balance), one-shot Id/DocNumber lookups and narrow windows (a DocNumber prefix, a single customer, a TxnDate range of a week or less) keep the single full fetch. A record changed between the two requests is returned with its current values; one deleted in between is omitted. Setting TKB_QUERY_TWO_PHASE=off on the gateway restores the single full fetch.

Limits and error codes. A gateway-side fetch is capped at 5,000 records — 1,000 for transactions fetched with line items (about 30 ms and 2.5 KB each on Desktop; COUNT(*) and header-only column lists skip lines and keep 5,000, and a two-phase scan's slim rows carry no lines, so it keeps 5,000 too). Hitting the cap is UNSUPPORTED_QUERY / HTTP 400 (narrow with a TxnDate or LastUpdatedTime range); syntax and unknown-property errors are 4000 / HTTP 400.

Errors ​

  • Invalid syntax (OR, an unquoted date, an unterminated string, a bad MAXRESULTS) is QBO's QueryParserError: HTTP 400, code 4000.
  • An unknown property, or a wrong operator/value for a property, is QueryValidationError: property Foo not found in Customer: HTTP 400, code 4000. QBO properties Desktop has no equivalent for return UNSUPPORTED_QUERY naming the property.
  • A valid query TenkeyBridge can't answer reliably (the 5,000-record scan cap, deep STARTPOSITION on a list) returns UNSUPPORTED_QUERY naming the clause.
  • CompanyInfo, Preferences and Budget (synthesized) take only a bare SELECT * (and WHERE Id = ... on Budget); per-entity exceptions are listed under each entity's Query support section on the compatibility page.

Errors ​

We return QBO-style Fault JSON, so existing error handling keeps working. Anything Desktop genuinely can't do — or that TenkeyBridge has not shipped yet — returns a documented code. See Error codes.

Gap entities (no Desktop equivalent) and planned entities (not yet built) both return UNSUPPORTED_BY_DESKTOP with a message that links to the entity's compat section. Genuinely unknown entity names still return NOT_FOUND.

TenkeyBridge is an independent product, not affiliated with, endorsed by, or sponsored by Intuit Inc. QuickBooks, QuickBooks Online, and QuickBooks Desktop are trademarks of Intuit Inc., used only to describe compatibility.