Adding a Line Item to an Existing Sales Order via QBXML
Developers modifying Sales Orders through QBXML can append new line items by setting the transaction line identifier to negative one in the modification request.
When you are working with QuickBooks Desktop data through the QBXML interface and need to append a new line item to a Sales Order that already exists, the modification request structure can look ambiguous. The schema for modifying Sales Order line items appears to require a transaction line identifier for every line — which naturally raises the question of what identifier to use for a line that does not exist yet.
The Confusion Around SalesOrderMod
Developers who successfully query an existing Sales Order receive a response showing each line item with its own unique transaction line identifier. Those identifiers are assigned by QuickBooks when the line is originally created. When you turn around and build a SalesOrderMod request to modify that order, the schema shows that each line item block in the modification request requires one of those existing identifiers. For lines already on the order, this is straightforward: you pass back the identifier QuickBooks assigned, update any fields you want to change, and submit.
The problem is that the schema documentation does not make it obvious how to signal that a line is brand-new rather than an update to an existing one. Developers report reading through the object reference and not finding a clear answer, which leads to a stall when the goal is simply to add another item to the order.
The Accepted Solution
The resolution comes from a detail in the SDK documentation for the transaction line identifier field itself. To add a new line item in any transaction modification request — including SalesOrderMod — you set the transaction line identifier to -1.
In practice, your new line item block inside the modification request should look like this:
- Set the transaction line identifier value to
-1 - Include the item reference (either the list identifier or the full name)
- Include any other details for the line: description, quantity, rate, and so on
QuickBooks interprets the -1 value as an instruction to create a new line rather than modify an existing one. It then assigns a real transaction line identifier to the newly created line and returns that identifier in the response.
Modifying Existing Lines vs. Adding New Ones
The distinction matters because the two operations look almost identical in the modification request structure. For an existing line, you pass the actual transaction line identifier that came back when you queried the order. For a new line, you pass -1. Everything else — the item reference, quantity, rate, description — follows the same pattern regardless of whether you are updating or adding.
If you are modifying multiple existing lines and adding new ones in the same request, you can include multiple line item blocks in the modification request. Each existing line carries its real identifier; each new line carries -1. QuickBooks processes them all in a single round trip.
A Note on the Transaction Line Identifier
The transaction line identifier was introduced with version 2.0 of the SDK. In earlier versions, it was always returned as zero, which is why older code samples and references may not treat it as meaningful. Current development should target a modern SDK version where the identifier is fully supported for both querying and modifying transactions.
Key Takeaway
The answer to this problem is a single value. When the schema requires a transaction line identifier and you are creating a line that has no identifier yet, pass -1. QuickBooks handles the rest, assigns the new identifier, and returns it so you can reference that line in future operations.