NetSuite Writes What It Receives

"The lines are out of order."

That sentence usually means an integration delivered lines in a sequence NetSuite didn't expect, and nobody controlled it. This is not a display quirk. It is a sequencing problem in your data.

Index vs. Sequence

NetSuite assigns each transaction line an internal index at creation time. That index is immutable — it is how NetSuite tracks the line internally. Display order is separate, controlled by a sequence value assigned at insert time, server-side, based on when the line was created relative to other lines on the record.

When a transaction is created through the UI, these stay roughly aligned. When anything else touches the record — a script, an API call, an import — they can drift.

The display sequence reflects insertion order. If your integration submits lines in a payload order that does not match your intended display order, NetSuite stores them exactly that way. The data is correct. The order is wrong.

Where It Breaks

REST and SOAP calls submit lines as arrays. If your middleware pulls from a source system where lines are sorted by internal ID, and that order does not map to your intended display sequence in NetSuite, the result is visually wrong — the integration succeeded, the data came through, but the sequence is off.

SuiteScript line writes reflect loop iteration order. If you are iterating over a saved search result without an explicit sort, you are depending on a guarantee that does not exist. I have seen environments where a search returned lines in different orders on different days based on index state. That is a production incident, not a hypothesis.

The delete-and-reinsert refresh pattern compounds this silently. New lines always append to the end of the sublist, after whatever remains. A CSV import that refreshes by clearing and reloading can scramble order on every run.

Concurrent writes are the hardest case. If a workflow fires while a scheduled script touches the same sublist, sequence assignment becomes a race. On high-volume environments where timing overlaps, line order is genuinely unpredictable.

Downstream Damage

The visible cost is users complaining the transaction looks wrong. The less visible cost is downstream: reports built with assumed positional relationships, fulfillments that pick by line order, integrations that read lines back out and expect the primary item first.

When sequence is wrong, workarounds accumulate. Users manually reorder lines. A scheduled script runs nightly to fix order. A beforeSubmit user event re-sorts on save. None of that addresses the root cause. It buries the problem under correction code.

Those workarounds become institutional knowledge: "Yeah, just run the reorder script after the import." That is not a process. That is a cover story for a design problem nobody fixed.

The Fix Is Upstream

Sort your payload before submitting. Whatever field drives the intended display order in the source system — line number, item sequence, priority — sort on it before you build the body. Do not trust middleware to preserve order between layers.

In SuiteScript, sort explicitly before your loop. Build the array, sort it, then iterate. One .sort() call prevents an entire category of support ticket.

For delete-and-reinsert refresh patterns, question whether you actually need them. Update in place where you can. When you cannot, explicitly control insertion order — pass it as a field if the target record supports it.

Bottom Line

Out-of-order lines are not a NetSuite bug. They are the correct behavior of a system that assigns sequence at insert time, applied to a data flow that did not control insertion order.

The fix is almost always upstream: sort before you submit, control iteration order in your scripts, and stop assuming NetSuite will infer the order you intended.

It does not infer anything. It writes what it receives, in the order it receives it.