Why is Avalara rejecting a sales invoice with a DocumentCodeConflict error?

What a document code actually is

Every transaction created in AvaTax carries a document code — an internal reference string your integration assigns, used to get, adjust, settle, or void that specific transaction later. Avalara's own model documentation describes it as "the internal reference code used by the client application," and notes that if you leave it blank, AvaTax assigns a GUID automatically. The code is how AvaTax tells two transactions apart — which is exactly what breaks when the same code shows up twice.

Why the conflict happens

AvaTax treats a committed transaction as finalized. Once a document code has been committed, that code is reserved and cannot be reused for a different transaction — Avalara's own DocumentCodeConflict error documentation states this directly. In practice, this shows up in one of two ways: a retry after a network timeout resubmits the same invoice with the same code, not realizing the first attempt actually succeeded and committed; or a downstream system reuses an invoice number as the document code for a genuinely different transaction — a credit memo, or a corrected invoice — without checking whether that number was already used.

The uncommitted case is not the safe case it looks like

If the original transaction with that code is still uncommitted, AvaTax won't raise DocumentCodeConflict — but that's not the same as safely deduplicating. A real sandbox replay (recorded internally as TD-2026-140) submitted the same uncommitted SalesInvoice document code twice, and both requests succeeded, each returning a different transaction id. AvaTax does not merge or reject the second submission; it creates a second document that happens to share a code with the first. The absence of an error is not confirmation that nothing duplicated — checking for an existing uncommitted document with that code before resubmitting is the only way to know.

If the original is committed

Don't resubmit the code at all: call the adjust endpoint to modify it, or the void endpoint to cancel it. If the transaction has already been reported to a tax authority, neither adjust nor void is available — the fix is to create a new, separate reverse transaction with opposite amounts, rather than trying to touch the original.

The fix that prevents it from recurring

Do the opposite of generating a fresh code per attempt: derive the document code deterministically from the source invoice or order — something stable across retries, not a GUID minted fresh each call — and reuse that exact code on every retry. A DocumentCodeConflict on a retry then becomes useful information: it tells you the earlier attempt already committed, not that something is broken. Generating a new code on every retry removes AvaTax's only way of recognizing a repeat, and is precisely what produces a duplicate — for both the uncommitted case above and the committed case DocumentCodeConflict is meant to catch.