> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upwell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deleting and archiving

> What DELETE actually does on each resource — hard vs. soft — and whether your external key is freed for reuse.

## 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](/api-guides/syncing-foundation-entities#vendors) — 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.

<Tip>
  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.
</Tip>