Delete and merge records

Deactivating a list record keeps its history and hides it from active lists. Deleting requests removal and requires confirm=true on resources with a typed list delete. Merging moves references from the record in the path into mergeIntoId, then removes the source. Back up the company file before irreversible maintenance and confirm the source and target with the customer.

Deactivate or delete a list record

Prefer an update with isActive: false for a customer, vendor, item or other list record with history. Use the resource’s update schema and current revision when required.

A typed list delete reads the record back in the same request. HTTP 200 means QuickBooks accepted the request; inspect the action result:

Result	What to do
deleted: true	The readback no longer returns the record. Remove its active mapping in your application.
deleted: false	QuickBooks kept the record. Check deactivated, isActive and retainedBecause; an inactive record can still reserve its name.
deleted: null	Readback failed and QBD_DELETE_NOT_VERIFIED warns that removal is unverified. Inspect the record before making another write.

On Enterprise 24, customer deletion removed the record in single-user mode and retained it inactive in multi-user mode. Other list types can have their own restrictions. Arrange single-user maintenance when removal matters and verify the result. See customer delete and inventory-site delete.

QuickBooks can refuse deletion because transactions or other records use the object. Follow QBD_OBJECT_IN_USE; do not remove accounting history just to defeat the dependency. Deactivate instead when appropriate. Unit of measure sets cannot be deleted through the SDK; make them inactive in QuickBooks.

Merge into the record you want to keep

The path ID is the source that disappears. mergeIntoId is the target that remains. Both must be the same record type. Retrieve both records before preparing the request and send:

• revisionNumber, the current source revision.
• mergeIntoId, the target ID.
• mergeIntoRevisionNumber, the current target revision.
• confirm: true, explicit confirmation of the irreversible change.

A stale revision returns QBD_REVISION_NUMBER_STALE. When the session reports multi-user mode, the API refuses merges with QBD_REQUIRES_SINGLE_USER_MODE before sending. Customer and class merges succeeded in single-user mode on the tested Enterprise 24 installation. Other merge types can have their own restrictions.

Pause updates, wait for the active update to finish, wait 15 seconds and exit the Web Connector before switching modes. Ask other users to save their work and close the file. After the merge, retrieve the source and target, check the target’s references and update your application’s mappings. See customer merge, class merge and Multi-user office.

Private custom fields and transaction limits

Private custom-field definition deletes need single-user mode. Public definitions and assigned private definitions have additional restrictions. Some private value changes also fail in multi-user mode. Check the delete result and follow Custom fields rather than recreating a retained definition.

Transaction delete and void support is resource-specific. Existing vehicle-mileage trips are refused by the typed delete with QBD_OPERATION_UNSUPPORTED: native deletion returned 3160 and kept the trip on Enterprise 24. A vehicle used by mileage can also be refused for deletion. Contact support with the request ID before attempting cleanup. See Documented incompatibilities.

Retries and uncertain outcomes

Use one idempotency key per intended maintenance operation and keep it for retries within the seven-day retention period. The key prevents a supported retry from repeating a completed or uncertain request during that period; it does not prove QuickBooks removed a record. After expiry the key can be treated as new. Verify the earlier outcome before retrying old work.

If a write’s outcome is unknown, keep the original key and inspect the affected records before another write. See Idempotency and safe retries.