Appearance
The compatibility contract
We deliver the most QuickBooks Online compatibility we can, and we're honest about the rest. Reads are almost entirely compatible; writes are where QuickBooks Desktop's quirks show up. Every partial or unsupported case below comes with the exact fix.
Legend — Full: works unchanged · Partial: common cases work, see notes · None: not supported, returns an error code.
At a glance
| Entity | Read | Write | Headline difference |
|---|---|---|---|
| Bill | Full | Full | Account vs. item expense lines map cleanly |
| Customer | Full | Full | Sub-customer maps to Desktop Customer:Job |
| Invoice | Full | Partial | Line model, tax, and discount handling |
| Item | Partial | None | One Item becomes several Desktop item types |
| SalesReceipt | Full | Partial | Same as Invoice + deposit account |
| Vendor | Full | Full | 1099 / tax-ID field naming only |
Bill
Read: Full · Write: Full — Account vs. item expense lines map cleanly
| QBO field | Support | Notes |
|---|---|---|
| Line | Full | Account-based and item-based expense lines; other line types return UNSUPPORTED_BY_DESKTOP. Sparse updates cannot modify lines/memo/tax yet. |
| TotalAmt | Full | Read-only, computed by Desktop as AmountDue. |
| Balance | Full | Read-only, as in QBO. |
Everything else listed as full works unchanged.
Full fields
- VendorRef
- TxnDate
- DueDate
- DocNumber
- PrivateNote
Customer
Read: Full · Write: Full — Sub-customer maps to Desktop Customer:Job
| QBO field | Support | Notes |
|---|---|---|
| ParentRef | Full | Becomes a Desktop Job under the parent; FullName is colon-delimited. |
| Balance | Full | Read-only, as in QBO. |
| FullyQualifiedName | Full | Read-only, derived by Desktop. |
| Job | Full | Read-only, derived by Desktop. |
| CurrencyRef | Partial | Accepted and ignored — Desktop manages this itself; multi-currency mapping lands later. |
| PreferredPaymentMethodRef | Partial | Accepted and ignored — Desktop manages this itself; multi-currency mapping lands later. |
| PreferredDeliveryMethod | None | UNSUPPORTED_BY_DESKTOP — Desktop has no delivery-method preference. Remove the field from your payload. |
| Taxable | None | UNSUPPORTED_BY_DESKTOP — Desktop customers have no taxable flag; set tax codes on transactions instead. |
Everything else listed as full works unchanged.
Full fields
- DisplayName
- CompanyName
- Title
- GivenName
- MiddleName
- FamilyName
- PrimaryEmailAddr
- PrimaryPhone
- AlternatePhone
- Fax
- BillAddr
- ShipAddr
- Notes
- Active
Invoice
Read: Full · Write: Partial — Line model, tax, and discount handling
| QBO field | Support | Notes |
|---|---|---|
| CustomerMemo | Full | Maps to Desktop CustomerMsgRef by FullName; the message must already exist as a Desktop customer message. Sparse updates cannot modify lines/memo/tax yet. |
| Line | Partial | SalesItemLineDetail, GroupLineDetail, and DescriptionOnly map cleanly; DiscountLineDetail requires a Desktop discount item referenced via DiscountLineDetail.ItemRef; other DetailTypes (e.g. SubTotalLineDetail) return UNSUPPORTED_BY_DESKTOP. Group lines read back as GroupLineDetail without nested line expansion; Desktop discount lines read back as regular item lines referencing the discount item. Sparse updates cannot modify lines/memo/tax yet. |
| TxnTaxDetail | Partial | Set TxnTaxCodeRef explicitly; computed TotalTax alone is rejected. Sparse updates cannot modify lines/memo/tax yet. |
| LinkedTxn | Partial | Read-only; reflects applied payments, ignored on write — same as QBO. |
| TotalAmt | Full | Read-only, computed by Desktop as Subtotal + SalesTaxTotal. |
| Balance | Full | Read-only, computed by Desktop as BalanceRemaining. |
Everything else listed as full works unchanged.
Full fields
- CustomerRef
- TxnDate
- DocNumber
- BillAddr
- ShipAddr
- PONumber
- SalesTermRef
- DueDate
- PrivateNote
Not supported
- TxnTaxDetail.TotalTax supplied without TxnTaxCodeRef —
UNSUPPORTED_BY_DESKTOP: Desktop cannot honor a computed tax total. Set TxnTaxDetail.TxnTaxCodeRef or per-line TaxCodeRef explicitly. See COMPATIBILITY.md. - Line.DiscountLineDetail without an ItemRef (bare-percentage or amount-off discounts) —
MISSING_REQUIRED_DESKTOP_ITEM: Desktop discounts are items. Create a discount item in the company file and reference it as DiscountLineDetail.ItemRef. See COMPATIBILITY.md. - Nested/grouped line types other than SalesItemLineDetail, DiscountLineDetail, GroupLineDetail, and DescriptionOnly (e.g. SubTotalLineDetail) —
UNSUPPORTED_BY_DESKTOP: These line types do not map to QuickBooks Desktop sales transactions. Remove them or flatten to a supported DetailType. See COMPATIBILITY.md.
Item
Read: Partial · Write: None — One Item becomes several Desktop item types
| QBO field | Support | Notes |
|---|---|---|
| FullyQualifiedName | Full | Read-only in this release. |
| Active | Full | Read-only in this release. |
| Type | Partial | Service, NonInventory, Inventory, Group map; other Desktop types are omitted from query results. |
| Description | Full | Read-only in this release. |
| UnitPrice | Full | Read-only in this release. |
| Sku | Full | Read-only in this release. |
| QtyOnHand | Full | Read-only in this release. |
| IncomeAccountRef | Full | Read-only in this release. |
| ExpenseAccountRef | Full | Read-only in this release. |
| AssetAccountRef | Full | Read-only in this release. |
Everything else listed as full works unchanged.
Full fields
- Name
Not supported
- Item types other than Service, NonInventory, Inventory, and Group (assemblies, discounts, sales tax items, payment items, fixed assets, other charge, subtotal) —
UNSUPPORTED_BY_DESKTOP: Omitted from query results; a direct get by id on one of these Desktop items returns a 422 UNSUPPORTED_BY_DESKTOP fault. - Item create/update —
UNSUPPORTED_BY_DESKTOP: Lands in a later release.
SalesReceipt
Read: Full · Write: Partial — Same as Invoice + deposit account
| QBO field | Support | Notes |
|---|---|---|
| CustomerMemo | Full | Maps to Desktop CustomerMsgRef by FullName; the message must already exist as a Desktop customer message. Sparse updates cannot modify lines/memo/tax yet. |
| Line | Partial | SalesItemLineDetail, GroupLineDetail, and DescriptionOnly map cleanly; DiscountLineDetail requires a Desktop discount item referenced via DiscountLineDetail.ItemRef; other DetailTypes (e.g. SubTotalLineDetail) return UNSUPPORTED_BY_DESKTOP. Group lines read back as GroupLineDetail without nested line expansion; Desktop discount lines read back as regular item lines referencing the discount item. Sparse updates cannot modify lines/memo/tax yet. |
| TxnTaxDetail | Partial | Set TxnTaxCodeRef explicitly; computed TotalTax alone is rejected. Sparse updates cannot modify lines/memo/tax yet. |
| LinkedTxn | Partial | Read-only; reflects applied payments, ignored on write — same as QBO. |
| TotalAmt | Full | Read-only; Desktop computes it. |
Everything else listed as full works unchanged.
Full fields
- CustomerRef
- TxnDate
- DocNumber
- BillAddr
- PrivateNote
- DepositToAccountRef
Not supported
- TxnTaxDetail.TotalTax supplied without TxnTaxCodeRef —
UNSUPPORTED_BY_DESKTOP: Desktop cannot honor a computed tax total. Set TxnTaxDetail.TxnTaxCodeRef or per-line TaxCodeRef explicitly. See COMPATIBILITY.md.
Vendor
Read: Full · Write: Full — 1099 / tax-ID field naming only
| QBO field | Support | Notes |
|---|---|---|
| TaxIdentifier | Full | Maps to Desktop VendorTaxIdent. |
| Vendor1099 | Full | Maps to Desktop IsVendorEligibleFor1099. |
| Balance | Full | Read-only, as in QBO. |
Everything else listed as full works unchanged.
Full fields
- DisplayName
- Active
- CompanyName
- Title
- GivenName
- MiddleName
- FamilyName
- BillAddr
- PrimaryPhone
- AlternatePhone
- Fax
- PrimaryEmailAddr
- AcctNum