Appearance
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(theLine.Ida 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 anIdare merged from the current record. - A line with no
Idis added. - A line you leave out is deleted. To leave the lines untouched, omit
Lineentirely; header-only updates never touch lines. An emptyLine: []is rejected (2020) rather than deleting every line. - The same
Idtwice in one array is a2010fault; anIdthat is not on the record is a400.
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}/clearedstatuswith{"TxnId": "<Id>", "LineId": "<Line.Id>", "ClearedStatus": "Cleared"}.ClearedStatusisCleared,NotClearedorPending(Reconciledis QuickBooks' own and cannot be written).LineIdis optional. The answer is{"ClearedStatus": {"TxnId", "LineId"?, "ClearedStatus"}, "time"}. - Read it back:
GET /v3/company/{companyId}/clearedstatus?txnid=<Id>&txntype=Purchaseanswers in the same envelope,{"ClearedStatus": {"TxnId", "TxnType", "TxnDate", "Splits": [...]}, "time"}, with one split per bank or balance sheet posting, each withRole, aLineIdyou can send back, itsClearedStatus,AmountandSetByTxnIdon the split a request without aLineIdwould 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):
| Transaction | TxnId alone sets | LineId 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) |
Deposit | the deposit-to account (DepositToAccountRef) | that deposit line's source account, when it is a balance sheet account |
BillPayment (check) | the bank account | no lines: a LineId is 610 |
JournalEntry | the first line only (refused when that line is not on a balance sheet account) | that line's account |
Transfer | refused | refused |
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 passTxnType: "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
422naming the closing date (not reproduced live: qbXML cannot set a closing date). - The read-back accepts a
txndateparameter 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. requestidworks as on any write, and since the call is a set, repeating it is harmless. After a lost response, sendTxnTypewith the request: the gateway can then settle the outcome with a read (applied when every addressed split already shows the status), otherwise it answers502 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 /customerwith{"DisplayName": "Roof Repair", "IsProject": true, "ParentRef": {"value": "<customer Id>"}}.IsProject: trueneeds aParentRef(without one the answer is400code2020);IsProject: falsetogether with aParentRefis400code2010. 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(andJob: true).select * from Customer where IsProject = truereturns them. - Transactions:
ProjectRefon an Invoice, Estimate, SalesReceipt or CreditMemo sets the customer to the project. IfCustomerRefis also sent, the project wins. On read, a transaction whose customer is a job returnsProjectRefwith the same value and name asCustomerRef;CustomerRefis 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
TxnVoidRqhas noEditSequenceinput, so TenkeyBridge compares yourSyncTokento the record's currentEditSequencebefore voiding and returns5010 Stale Object Erroron a mismatch — the same as QBO.SyncTokenis required. - Residual race window.
TxnVoidRqtakes noEditSequence, so a change made in QuickBooks between our read and the void is not detected; theSyncTokencheck 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;GETthe record and do not retry. - Payment cannot be voided. qbXML has no void for
ReceivePayment; the call returns400 UNSUPPORTED_BY_DESKTOP— delete the payment instead. Every other entity also returns400. - Batch:
operation: "update"+optionsData: "void"(Batch guide). - What Desktop returns after a void (proven on QuickBooks Enterprise 24): the same
IdandTxnDate, totals and line amounts at0, andPrivateNoteprefixedVOID:. Invoice and SalesReceipt lines also getQty: 0; a BillPayment's applied-to-billLineentries disappear and the bills it paid reopen. Voiding an already-voided record succeeds and changes no amounts. A void does not reliably advance theSyncToken, 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
PrivateNoteprefixedVOID:, and its totals and line amounts go to0.00with the lines kept. A voided Bill readsBalance: 0.00(Desktop marks it paid). A voided JournalEntry has every line at0.00andVOID: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 theSyncToken, so re-read the record instead of building on it. - Voiding a check adds journal entries. When you void a
Purchaseof 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 toVOID: <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 exampleQuickBooks warning 530: The field "Name" is not supported by this implementation. (EmployeeDisplayNameno longer takes this path: Desktop derives it from the first, middle and last names, so a write naming a different one is refused with a400up front.) - TenkeyBridge ignored a field. On an Invoice, SalesReceipt, Estimate or CreditMemo create or update, a
TxnTaxDetail.TotalTaxsent without aTxnTaxCodeRefis not sent to QuickBooks, which computes the tax itself. If its figure differs from yours the header readsTxnTaxDetail.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
MAXRESULTSup 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 anX-TKB-Warningheader (MAXRESULTS 1000 reduced to 500; ...).QueryResponse.maxResultsis the number of rows returned, as in QBO. Page by advancingSTARTPOSITIONby the rows you received (or until an empty page), never by comparing the row count to theMAXRESULTSyou asked for: a client that stops at "fewer rows than I asked for" would stop after 500 and miss the rest. minorversionis 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/MAXRESULTSare ignored).- Column lists return exactly the listed properties (
Idis not added implicitly; dotted names such asMetaData.LastUpdatedTimekeep their nesting). ORDERBYsorts the whole filtered set beforeSTARTPOSITION/MAXRESULTSslice 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</>onTxnDatebecome 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.
| Entity | Applied by QuickBooks (fast) |
|---|---|
| All transactions — Invoice, SalesReceipt, Estimate, CreditMemo, Payment, RefundReceipt, Bill, VendorCredit, PurchaseOrder, BillPayment, Purchase, JournalEntry, Deposit, Transfer, TimeActivity | Id (=, 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, RefundReceipt | CustomerRef (=, IN) |
| Bill, VendorCredit, PurchaseOrder, BillPayment | VendorRef (=, IN) |
| Purchase | EntityRef — the payee (=, IN) |
| Invoice, Bill | Balance > 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, ExchangeRate | Id (=, 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, Item | FullyQualifiedName = / 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 |
| TaxAgency | Active 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 badMAXRESULTS) is QBO'sQueryParserError: HTTP 400, code4000. - An unknown property, or a wrong operator/value for a property, is
QueryValidationError: property Foo not found in Customer: HTTP 400, code4000. QBO properties Desktop has no equivalent for returnUNSUPPORTED_QUERYnaming the property. - A valid query TenkeyBridge can't answer reliably (the 5,000-record scan cap, deep
STARTPOSITIONon a list) returnsUNSUPPORTED_QUERYnaming the clause. CompanyInfo,PreferencesandBudget(synthesized) take only a bareSELECT *(andWHERE 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.

