---
id: WF-ACC-BKS-003
title: Remove an Unreferenced Unit
trigger: A caller with deletion permission removes a unit through the API or console.
product_area: accounting
module: books
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-ACC-BKS-001
  - CAP-ACC-BKS-016
moves:
  - STATE-ACC-BKS-001
  - STATE-ACC-BKS-002
crosses: []
idempotency: >-
  A repeat after successful deletion returns missing. A refused deletion remains
  refused until its blocking dependency or lock changes.
concurrency: >-
  The service locks the unit before deleting. Restricting foreign keys arbitrate
  new references racing the delete, including references to owned records that
  would cascade.
hops:
  - 'n': 1
    actor_or_service: Books service (transaction)
    action: Lock the selected unit and check deletion protection.
    anchor: >-
      services-accounting:modules/books/services/persistence/business-units.ts:deleteBusinessUnit
    seam: sync
    on_failure: Return missing or locked without deleting.
    left_inconsistent: This request removes no record.
    observer: the caller
    provenance: observed
    source: >-
      services-accounting:modules/books/services/persistence/business-units.ts:deleteBusinessUnit
  - 'n': 2
    actor_or_service: Books service
    action: 'Collect remaining GL, bank and merchant accounts and accounting projects.'
    anchor: >-
      services-accounting:modules/books/services/persistence/business-units.ts:accountKindsOfUnit
    seam: sync
    on_failure: Return a conflict identifying all collected blocking kinds.
    left_inconsistent: All unit configuration is retained.
    observer: the caller
    provenance: test
    source: >-
      services-accounting:modules/books/tests/integration/services/persistence/business-units.integration.spec.js#refuses
      a unit with GL, bank and merchant accounts, naming all three
  - 'n': 3
    actor_or_service: Database
    action: >-
      Delete the unit and cascade eligible currency rows, defaults, departments
      and calendar records.
    anchor: 'services-accounting:modules/books/db/business-units.table.ts:businessUnits'
    seam: sync
    on_failure: Roll back the cascade when a restricting reference prevents removal.
    left_inconsistent: The unit and cascaded configuration remain intact.
    observer: the caller
    provenance: test
    source: >-
      services-accounting:modules/books/tests/integration/services/persistence/departments.integration.spec.js#refuses
      the delete 409, naming the unit’s products
  - 'n': 4
    actor_or_service: Books service (refusal translation)
    action: >-
      Translate recognized database constraints into a useful dependent-record
      refusal.
    anchor: >-
      services-accounting:modules/books/services/persistence/configuration-refusals.ts:configurationRefusal
    seam: sync
    on_failure: >-
      An unrecognized constraint keeps its original database error rather than
      receiving the named translation.
    left_inconsistent: >-
      Error wording can be incomplete, but the failed transaction leaves data
      unchanged.
    observer: the caller; the service log
    provenance: observed
    source: >-
      services-accounting:modules/books/services/persistence/configuration-refusals.ts:STILL_REFERENCED
branches:
  - condition: Delete multiple selected units
    path: >-
      Run independent single-unit deletions; some units can succeed while others
      remain blocked.
waits: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/books/services/persistence/business-units.ts,
    configuration-refusals.ts
  - >-
    react-console at baf6dae3: components/configuration/standard.tsx,
    bulk-bar.tsx
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-DAT-001, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003]
---

# Remove an Unreferenced Unit

## What It Does

Unit deletion removes only configuration that belongs exclusively to an eligible unit. Accounts and projects require prior removal, and references from financial or product work can still prevent deletion of the unit or its cascaded calendar and departments.

## The Flow

```mermaid
flowchart TD
  h0["Lock the selected unit and check deletion protection."]
  h1["Collect remaining GL, bank and merchant accounts and accounting projects."]
  h0 --> h1
  h2["Delete the unit and cascade eligible currency rows, defaults, departments and calendar records."]
  h1 --> h2
  h3["Translate recognized database constraints into a useful dependent-record refusal."]
  h2 --> h3
```

## When Something Fails

A lock, retained account or project, or restricting database reference refuses removal. The unit and its cascades share a transaction. Known constraints become useful dependency messages; unknown ones can surface as less useful errors. Console bulk deletion is a collection of independent requests and can finish partially.

## Open Design Questions

Useful dependency translation needs maintenance as new references are added. The service does not provide a restoration operation for physically deleted configuration.