QuickBooks Online API rejects duplicate invoice numbers on creation
Developers creating invoices through the QuickBooks Online API encounter errors when DocNumber values collide, despite no stated uniqueness requirement in the documentation.
QuickBooks Online users building custom integrations have reported unexpected errors when attempting to create invoices through the Accounting API. The issue surfaces when an invoice is submitted with a document number that already exists elsewhere in the company file. Rather than accepting the record, the API rejects it — and the documentation does not make it obvious why.
The confusion centers on the DocNumber field, which corresponds to the invoice number visible in the QuickBooks interface. According to the field documentation, there is no explicit statement that DocNumber must be unique. In practice, however, QuickBooks Online treats it as a unique identifier in most scenarios and will block creation when a duplicate is detected.
Why the error appears
When a developer or integration sends a POST request to create an invoice, the API validates the incoming data against existing records. If the DocNumber value matches one already assigned to another invoice, the request fails. The error payload itself can be opaque — in some cases returning a structure that does not clearly indicate the root cause, leading developers to suspect a malformed request or an authentication problem rather than a simple numbering conflict.
This tends to catch people off guard because QuickBooks can also auto-generate DocNumber values. If an integration assigns numbers manually and the sequence overlaps with numbers the system has already used or generated, the collision triggers the rejection.
The accepted workaround
The formally accepted solution in the developer community is to append a specific query-string argument to the API request URL. Adding include=allowduplicatedocnum tells QuickBooks Online to accept the invoice even when the DocNumber is not unique.
This parameter is not a global configuration change. It is applied per request, meaning each individual API call that may involve a duplicate document number must include the argument explicitly. Developers who only need the occasional duplicate can add it selectively without worrying about broader side effects on their integration.
For teams that prefer to avoid duplicate numbers entirely, the alternative is to let QuickBooks generate the DocNumber automatically by omitting the field from the request payload. This sidesteps the uniqueness check altogether but removes control over the numbering scheme.
Complications with third-party libraries
The workaround is straightforward when you are sending raw HTTP requests directly to the QuickBooks Online API. It becomes more complicated when relying on a wrapper library.
The most widely used Node.js library for QuickBooks Online does not natively support passing the allowduplicatedocnum parameter. Its invoice-creation method builds the request URL internally and does not expose a mechanism for appending custom query arguments. The underlying create method uses a fixed URL string with no provision for additional parameters.
Developers who need the duplicate-number behavior while using that library are left with a handful of options, none of them ideal:
- Modify the library’s source directly to accept the parameter, which creates a maintenance burden every time the library is updated.
- Fork the project and maintain a custom version with the change applied.
- Request that the library maintainers add support for arbitrary query parameters in a future release.
- Switch to a different library that offers more flexibility.
- Bypass the library entirely for this specific call and send a raw request to the QuickBooks Online API from your own code.
For most integrations, the last option — sending a direct HTTP request when a duplicate document number is needed — is the least disruptive path. It avoids forking dependencies and keeps the rest of the integration intact.
Practical takeaway
The core issue is a gap between what the documentation implies and how QuickBooks Online actually behaves. DocNumber uniqueness is enforced by default, and the documentation does not call attention to that fact prominently enough for developers to anticipate the error. Once you understand the constraint, the per-request parameter resolves it cleanly — provided your tooling lets you pass it through.