QuickBooks API "Duplicate Document Number Error" on bill create

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

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.

1. If found, return it as the result of the create.

Expected: Idempotent behavior.

1. If not found, ensure DocNumber is set explicitly on create.

Expected: No auto-number collisions.

1. Retry the create.

Expected: A new bill.

1. 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/psta3Hd6SlcHpgpP69jAwhTg