How do I avoid duplicate Avalara tax transactions at period close?

Why retries are the usual cause

A duplicate tax transaction at period close almost never comes from someone deliberately creating a transaction twice. It comes from a network timeout, a dropped response, or a retry policy that doesn't know whether the first call actually succeeded on Avalara's side before failing on the client side. If that retry logic generates a fresh documentCode for the second attempt — instead of resending the same one — AvaTax has no way to recognize it as the same transaction, and both can end up committed.

What Avalara's DocumentCodeConflict error actually tells you

AvaTax reserves a documentCode once its transaction is committed, scoped to a company and document type. Sending the same code again after that point returns a DocumentCodeConflict error rather than silently overwriting or duplicating anything — which is actually the safety net that catches the retry problem, provided the retry logic reuses the original code instead of generating a new one on failure. A code that was never committed (an errored or voided attempt) can be reused without conflict, which is deliberate: it's what makes a genuine retry-with-the-same-code pattern work correctly.

The fix, concretely

Derive documentCode from something already unique and deterministic in the source system — an invoice number, an order ID — rather than a randomly generated value created fresh on each call. On a failed or ambiguous response, retry with that same code; if AvaTax returns DocumentCodeConflict on the retry, that's confirmation the original attempt actually succeeded, not a new error to work around. Reserve void or delete actions for transactions genuinely meant to be cancelled, not as a routine way to clear a code before reissuing it.