## TL;DR

QuickBooks requires unique document numbers on bills when the preference is enabled, and retries collide with the already-created bill. Check for an existing bill with the document number before creating, and reuse the vendor-plus-invoice-number as your idempotency key. On duplicate errors, query the existing bill instead of failing.

## Error

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

## Steps

1. Query for an existing bill with the same DocNumber and vendor.
   Expected: The existing bill, if any.
2. If found, return it as the result of the create.
   Expected: Idempotent behavior.
3. If not found, ensure DocNumber is set explicitly on create.
   Expected: No auto-number collisions.
4. Retry the create.
   Expected: A new bill.
5. Key retries on vendor plus invoice number.
   Expected: Safe retries forever.

## When to use

- QuickBooks Online API bill creates fail
- Retry logic around bill creation
- AP integrations with QuickBooks

## When not to use

- NetSuite or Xero duplicate errors
- UI bill entry
- Non-bill objects

## Compatibility

QuickBooks Online Accounting API (v3).

## Variant phrasings

### QuickBooks duplicate document number bill

### DocNumber already used bill

### idempotent bill create QuickBooks

## Root cause

The uniqueness check plus naive retries creates the collision: the first attempt posts, the retry sees a duplicate. Without a pre-check, every retry after a transient failure looks like a duplicate.

## Edge cases

- The preference can be disabled, but keeping it on plus idempotency is safer
- DocNumber scoping is per-company; multi-company setups need care
- Sparse updates on bills need the latest SyncToken

## Provenance

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