Deleting and archiving

DELETE does not mean the same thing on every resource, and the difference decides whether you can reuse an external key afterwards.

Resource	What `DELETE` does	Reusing the key afterwards
Customer	Hard delete. The row is gone, and its addresses are deleted with it.	Frees `(sourceSystem, sourceSystemId)` for reuse. Soft-deleting instead — `PUT` with `deletedAt` — frees it too, and is recoverable.
Carrier	Hard delete. Carriers have no archive state at all.	Frees `(sourceSystem, sourceSystemId)`. In practice you rarely need this: `POST /api/rest/carriers` already no-ops on a duplicate key rather than failing.
Company	Soft delete. The row is retained with `deletedAt` set and disappears from the app.	Frees the company name for reuse. Names are unique case-insensitively per tenant, so `Acme` and `ACME` collide.
Address	Hard delete. No archive state.	n/a — addresses have no external key.
Vendor	Hard delete. No archive state.	See the vendors warning — it fails if a bill still references the vendor.

Two consequences that surprise people:

You cannot delete an address a carrier points at. addressId and billingAddressId are restrict-on-delete. Clear the reference on the carrier first, then delete the address.
Deleting a company does not delete its addresses. Because the delete is soft, the cascade never fires — the address rows survive, still pointing at a company that no longer appears anywhere. Clean them up yourself if you care.

For customers, prefer the soft delete (PUT with deletedAt) over DELETE. It frees the external key exactly the same way, but it’s reversible and it doesn’t take the customer’s address history with it.

⌘I

​Deleting and archiving

Deleting and archiving