QuickBooks Online API Rejects Custom Tax Code IDs on Invoice Lines
Developers submitting invoices through the QuickBooks Online API hit an error when using numeric tax code references instead of the required TAX or NON values for US company files.
A developer submitting invoices through the QuickBooks Online programming interface encountered a rejection error when assigning different tax codes to individual line items. The API returned a message stating that the line tax codes in the request were invalid, noting that valid tax codes for United States company files should be “TAX” or “NON” rather than the numeric identifiers the developer had supplied.
The developer had structured an invoice request with multiple line items, each referencing a specific tax code by its internal database identifier — in this case, the numeric values 8 and 9. Those tax codes were defined and active within the QuickBooks Online company file, which led the developer to assume the numeric references would be accepted. The rejection indicated otherwise, flagging both supplied values as invalid for a US-based account.
What the Error Message Actually Says
The accepted answer in the community thread points out that the developer was focused on whether multiple, differing tax codes could be applied to separate lines on a single invoice. The error message, however, was addressing a different problem entirely. The issue was not that the API disallows different tax codes on different lines. The issue was that the specific values submitted were not recognized as valid tax code references for a US company file.
For United States QuickBooks Online company files, the programming interface accepts only two values in a line-level tax code field: “TAX” or “NON.” These are textual identifiers, not numeric references to specific tax code records. Submitting a numeric identifier — even one that corresponds to a legitimate, active tax code in the company file — produces the rejection the developer experienced.
Why Numeric Tax Code IDs Fail
The confusion appears to stem from how tax codes are represented inside the QuickBooks Online interface versus how they must be referenced through the API. Within the application, tax codes are displayed with names and internal identifiers. A developer querying the list of available tax codes will see entries with numeric IDs. It is reasonable to assume those numeric IDs can be passed back when creating transactions.
For US company files, though, the line-level tax code field operates on a simpler model. Rather than pointing to a specific tax rate or tax code record, the field acts as a switch. Setting it to “TAX” indicates that the line item is taxable. Setting it to “NON” indicates that it is not taxable. The actual tax rate applied is determined by the tax rate associated with the customer or the transaction as a whole, not by the line-level reference.
The Fix
The solution is straightforward. Replace any numeric tax code reference in each line item with the appropriate textual value. For a taxable line, the tax code reference should be set to “TAX.” For a non-taxable line, it should be set to “NON.” No other values are accepted for US company files.
Behavior Outside the United States
The accepted answer notes that QuickBooks Online company files based outside the United States follow a different pattern. In other regions — Canada, the United Kingdom, Australia, and similar jurisdictions — the tax system is more granular, reflecting taxes such as GST, HST, PST, and VAT. For those company files, the API does accept references to specific tax codes rather than limiting the field to a simple taxable-or-not toggle. Developers working with non-US company files should consult the regional tax model for that country to determine the valid set of references.
Key Takeaway for Developers
The broader lesson is that error messages in the QuickBooks Online API tend to be literal. When the response states that valid values are “TAX” or “NON,” it means exactly that — no substitution of internal identifiers will work for a US file. Developers building integrations that span multiple regions should account for the possibility that the same field accepts different value formats depending on the country setting of the company file. Hard-coding numeric tax code IDs pulled from a query of existing records will work in some regions but fail in the United States, where the two-value toggle is the only accepted format.