Stripe QuickBooks sync: "duplicate invoice number" during sync

TL;DR

QuickBooks enforces unique invoice numbers (doc numbers) per company, so the sync must generate numbers that cannot collide: prefix Stripe invoice numbers with a source tag or let QuickBooks auto-number. On collision, check whether the existing invoice is the same Stripe invoice (skip) or a real conflict (renumber). Never silently overwrite.

Error

```text
Duplicate Document Number Error: You must specify a different number.
This number has already been used.

## Steps

1. Read the failing invoice number and find the existing QuickBooks invoice carrying it.
   Expected output: You know whether it is a true duplicate or a re-sync of the same invoice.
2. If the existing record is the same Stripe invoice (match by stored Stripe id), mark synced and move on.
   Expected output: Re-syncs stop erroring.
3. If it is a genuine collision, change your numbering: prefix Stripe numbers (e.g. ST-INV-1234) or enable QuickBooks auto-numbering.
   Expected output: Future invoices cannot collide.
4. Store the Stripe invoice id on the QuickBooks invoice as a private note or custom field.
   Expected output: Every synced invoice is traceable both ways.
5. Backfill or renumber the collided invoices, then re-run the sync.
   Expected output: The backlog clears.

## When to use

- QuickBooks sync fails on duplicate document number
- Re-syncs collide with existing invoices
- You design the invoice numbering scheme

## When not to use

- The error is about duplicate customers or items (different dedup)
- Tax mapping fails (different map)
- You sync to Xero instead (Xero numbering rules differ)

## Compatibility

QuickBooks Accounting API docNumber uniqueness; Stripe invoice numbers. Any sync middleware or custom code.

## Variant phrasings

### ### QuickBooks duplicate document number Stripe sync

### ### invoice number collision QuickBooks API

### ### Stripe invoice number prefix QuickBooks

## Root cause

QuickBooks treats the document number as a unique business key per company file, while Stripe invoice numbers are only unique within Stripe. Two systems minting numbers independently will eventually collide, and re-syncs without idempotency keys replay the same numbers.

## Edge cases

- QuickBooks auto-numbering fills gaps differently than Stripe sequences; pick one source of truth
- Deleted QuickBooks invoices can still reserve numbers; check the audit log
- Multi-entity QuickBooks companies each enforce uniqueness separately

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_dGpqlur6Je0Tr3X7oaqu4w