Void vs. Delete in QuickBooks Desktop via API: What Each One Leaves Behind
- void invoice quickbooks desktop api
- quickbooks void vs delete
- quickbooks operation=void
- delete transaction quickbooks api

Quick answers
- What's the difference between void and delete in QuickBooks? A void keeps the transaction in the file with its number and date intact but zeroes every line amount; a delete removes the record entirely so nothing but an audit-log entry remains.
- How do I void an invoice through the QuickBooks Desktop API?
POST /v3/company/{realmId}/invoice?operation=voidwith theIdand currentSyncTokenin the body — the same call shape you already use against QuickBooks Online. - Which transaction types support operation=void? The QBO set: Invoice, SalesReceipt, Purchase (Check, CreditCardCharge, CreditCardCredit) and BillPayment (check and credit-card families). Desktop can also void Bill, VendorCredit, Deposit, JournalEntry, InventoryAdjustment and CreditMemo, which TenkeyBridge exposes as extensions. Details per type are in the compatibility matrix.
- Can I void a customer payment? No — qbXML has no void operation for
ReceivePayment, so you delete the payment and re-enter a corrected one. - What happens if my SyncToken is stale? You get error 5010, the object-has-been-modified fault; re-read the transaction and retry with the fresh token.
The question is really about the audit trail
Void and delete are not two ways to do the same thing. They produce different files. A month later, when Pat Owner at ExampleCo is reconciling a bank account and asks "what happened to invoice 1047," the answer depends entirely on which call your integration made.
A void leaves a skeleton: same transaction number, same date, same customer, zeroed amounts, and a VOID: prefix on the memo. The record still appears in registers and in numbered sequences. A delete removes the object; the transaction number disappears from the sequence, and the only trace is a line in QuickBooks' own audit log — which your API client cannot read back.
The decision rule that holds up in practice is short:
Void what was issued. Delete what was never real.
If the document left your building — a printed check, an emailed invoice, a receipt handed to a customer — void it. Somebody out there has a copy with that number on it, and the file should explain where it went. If the transaction was a sync bug, a duplicate posted by a retry, or a test record nobody saw, delete it. Keeping a zeroed phantom around only makes the register harder to read.
How void works over the API
The request shape matches QuickBooks Online exactly. You send the operation as a query parameter and a minimal body containing the identity of the object:
POST /v3/company/9130354xxxxxxxx/invoice?operation=void HTTP/1.1
Host: api.tenkeybridge.com
Authorization: Bearer {token}
Content-Type: application/json
{
"Id": "1047",
"SyncToken": "2"
}
The response is the full transaction object as it now exists in the file:
{
"Invoice": {
"Id": "1047",
"SyncToken": "2",
"DocNumber": "1047",
"TxnDate": "2025-03-14",
"CustomerRef": { "value": "81", "name": "ExampleCo" },
"TotalAmt": 0,
"Balance": 0,
"PrivateNote": "VOID: original amount 2,450.00",
"Line": [
{
"Id": "1",
"Amount": 0,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": { "ItemRef": { "value": "14" }, "Qty": 0 }
}
]
}
}
Three things to notice.
The SyncToken is checked, but don't count on it moving. If you cached the object earlier and send an old token, you get a 5010 fault — the same object-has-been-modified error you'd get on a normal update. After the void, though, Desktop does not reliably advance the token, so re-read the record before your next write instead of predicting the new value. That matters more on Desktop than you might expect, because a bookkeeper sitting in the UI can touch the same transaction between your read and your write. Re-read, confirm the transaction is still the one you meant to void, then retry. If you're mapping these faults into your existing QBO error handling, we went through the full translation layer in decoding QuickBooks Desktop errors.
The lines survive. Line items stay on the transaction with zero amounts and zero quantities. This surprises people who expect the line array to come back empty. It's QuickBooks' behavior, not a bridge artifact — the document keeps its shape so a human can still see what it was for.
The memo gets rewritten. QuickBooks prefixes the memo field with VOID:. If you were using PrivateNote to carry your own correlation ID, that ID is now sharing the field with QuickBooks' prefix, and the field has a length limit. Store your external key somewhere you control — a custom field, or your own mapping table keyed by Id — rather than relying on a memo surviving a void intact.
Void is idempotent enough, but not a retry target
Voiding an already-voided invoice succeeds and changes no amounts, so the end state is identical. That also means a success response can't tell you whether this call voided it or it was already void. Check TotalAmt and the memo prefix rather than inferring from the HTTP status. One more case: if the void lands but the follow-up read fails, you get 502 VOID_APPLIED_READBACK_FAILED. The void was applied; GET the record and do not retry.
The more dangerous case is a timeout on the void itself. A 504 means your request may or may not have landed; a 503 usually means it never did. That distinction is worth getting right before you wire a retry loop around any write, and we covered it specifically in 503 vs. 504 from QuickBooks Desktop.
What supports void, and what "partial" means
Ten object families accept operation=void. The first four are the ones QuickBooks Online voids; the rest are things QuickBooks Desktop can void and QBO can't, so a QBO client never sends them and nothing changes for existing code:
| Object | Covers | Where it comes from |
| --- | --- | --- |
| Invoice | Invoices | QBO |
| SalesReceipt | Sales receipts | QBO |
| Purchase | Check, CreditCardCharge, CreditCardCredit | QBO |
| BillPayment | Bill payment check, bill payment credit card | QBO |
| Bill | Bills (a voided bill reads Balance: 0.00) | Desktop extension |
| VendorCredit | Vendor credits | Desktop extension |
| Deposit | Deposits | Desktop extension |
| JournalEntry | Journal entries (VOID: lands on the first line's memo) | Desktop extension |
| InventoryAdjustment | Inventory adjustments | Desktop extension |
| CreditMemo | Credit memos (an applied one releases its credit) | Desktop extension |
The compatibility matrix marks each of these partial because the per-type results differ: a JournalEntry comes back with both lines on the debit side, a voided BillPayment's bills reopen, a voided CreditMemo that had been applied reopens the invoice's balance. Read the notes for the exact types you touch. The voids section of the concepts guide has the behavioral details.
Everything else (Transfer, Estimate, and the rest) answers 400 to a void. For those, your options are to delete, or to post a reversing entry and leave both in the file. Even where a void exists, a reversing entry is often the right call for a journal entry in a closed period, where a void would silently change a reported number.
The customer payment exception
Payment — a ReceivePayment in Desktop terms — cannot be voided through the API. The qbXML request set simply does not include a void operation for it. There is no workaround at the protocol level, and no bridge can manufacture one.
What you do instead:
- Read the payment and capture which invoices it was applied to (
Line[].LinkedTxn). - Delete the payment:
POST /v3/company/{realmId}/payment?operation=deletewithIdandSyncToken. - Re-enter a corrected payment with the right amount and the right links, if one is warranted.
Deleting a payment unapplies it, which means the invoices it covered return to open with their balances restored. That's the behavior you want — but it also means the gap between step 2 and step 3 is a window where ExampleCo's AR aging looks wrong. Keep it short, and don't put a human approval step in the middle of it.
One more consequence: if the payment was part of a deposit, deleting it leaves the deposit line dangling. Check for a linked deposit before you delete, and plan to fix it in the same run.
Delete: what actually disappears
POST /v3/company/9130354xxxxxxxx/invoice?operation=delete
{ "Id": "1047", "SyncToken": "2" }
The response confirms the deletion and the object is gone. Specifically gone:
- The transaction number is removed from the sequence. QuickBooks does not renumber; you get a hole.
- Any links from other transactions — payments applied to a deleted invoice, bills paid by a deleted check — are severed, and the counterpart transaction's balance changes.
- The object will not appear in subsequent queries, and it will not appear in change data capture the way an update does. Deletes do surface in CDC, but the 30-day window and object cap apply the same as anything else; if your downstream system polls infrequently it can miss a delete entirely. That failure mode is worth reading about before you rely on CDC to propagate removals — see the 30-day window and 1,000-object cap.
If your system is the source of truth and QuickBooks is a downstream mirror, delete is often correct: a record that shouldn't exist upstream shouldn't exist downstream. If QuickBooks is the book of record for an audited entity, lean hard toward void and let the accountant decide.
A decision procedure you can code
if transaction is a customer Payment:
delete and re-enter # no void available
elif type has no void (Transfer, Estimate, ...):
delete, or post a reversing entry
elif document was issued externally (printed, emailed, cashed):
void # preserve the number
elif transaction is in a closed accounting period:
post a reversing entry # don't touch the period
elif transaction was created in error by your integration:
delete # it was never real
else:
void # default to preserving the trail
Two guardrails worth adding around that logic.
Confirm before you write. Read the transaction immediately before the void or delete and verify it still matches what you intended to change — same amount, same customer, same date. Desktop files are multi-user; a bookkeeper may have edited the thing you're about to zero. The general problem of not clobbering human edits is the same one we worked through in sparse updates vs. full replacement.
Don't batch destructive operations casually. A batch request against Desktop is not a transaction — a partial failure leaves some items applied and some not, with no rollback. Voiding twelve checks in one batch and getting three faults is a state you have to reconcile by hand. Issue destructive writes individually and record the outcome of each, for the reasons laid out in batch requests are not transactions.
Testing this without wrecking a real file
Voids and deletes are the operations you least want to debug in production. Both are easy to get wrong in ways that are tedious to undo — a deleted payment that unapplied six invoices, a voided check that was already reconciled.
Run them against a throwaway company file first. The TenkeyBridge sandbox gives you a Desktop file you can void and delete against freely, with the same REST surface you'll hit in production, so you can confirm exactly what the response body looks like for your object types before any of it touches ExampleCo's books.
FAQ
Which transaction types can I void through the API?
Invoice, SalesReceipt, Purchase (which covers Check, CreditCardCharge and CreditCardCredit) and BillPayment (check and credit-card bill payments), the same set QuickBooks Online voids. QuickBooks Desktop can also void a Bill, VendorCredit, Deposit, JournalEntry, InventoryAdjustment and CreditMemo, and TenkeyBridge exposes those on the same call as extensions. All four are listed as partial support — check the per-object notes in the compatibility matrix for the subtypes and edge cases that may still return a fault.
What does a voided invoice look like afterwards?
It stays in the file with its original DocNumber, TxnDate and CustomerRef. TotalAmt and Balance become 0, every line amount and quantity becomes 0, the memo gains a VOID: prefix, and the SyncToken increments. It remains queryable and still occupies its slot in the numbering sequence.
Can I void a customer payment, and what do I do instead?
No. qbXML has no void operation for ReceivePayment, so the API can't offer one. Capture the payment's LinkedTxn entries, delete it with operation=delete, then post a corrected payment. Deleting restores the balances on the invoices it was applied to.
When should I delete instead of void?
When the transaction was never real to anyone outside your system — a duplicate from a retry, a record created by a mapping bug, a test entry. If a copy of the document exists outside QuickBooks, void instead so the number still has an explanation attached to it.
Does voiding a check affect a completed bank reconciliation?
It can. Voiding a transaction that's already marked cleared changes the cleared balance for that period and will show up as a discrepancy next time someone reconciles. Check the cleared status before voiding anything dated in a reconciled period, and route those cases to a human.
Will a void or delete show up in change data capture?
Yes, both appear in CDC results, but subject to the usual Desktop constraints — the lookback window and the object cap. A downstream system that polls rarely can miss a delete, so if removals matter to you, reconcile periodically by ID rather than relying on the change feed alone.
Do voids work the same way on hosted QuickBooks?
The API call is identical. The practical difference is concurrency: hosted environments tend to have more simultaneous human users, which makes stale-SyncToken 5010 faults more likely on destructive writes. Read-then-write immediately, and handle 5010 as a normal retry-after-refresh case rather than an error. If you want to see the exact void response for your object types, the quickstart will have you issuing one against a sandbox file in a few minutes.