---
id: WF-ACC-TRX-004
title: Write off a balance and restore it
trigger: Staff abandon selected outstanding debt and may later restore it.
product_area: accounting
module: transactions
revision: 1
status: draft
design_intent: confirmed
origin: >-
  Andrew’s D19, M1-6 and §2.12 D-7 (reverse the write-off, then apply the
  payment),
  services-accounting:docs/architecture/accounting-2.0/02-decisions.md#2.12 The
  unified billing, dunning and collections decisions (Andrew, 2026-10-18)
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-ACC-TRX-004
moves:
  - STATE-ACC-TRX-003
  - STATE-ACC-TRX-001
crosses:
  - SVC-ACC-TRX-transactions
hops:
  - 'n': 1
    actor_or_service: Write-off commands
    action: >-
      Validate the invoice's outstanding lines, select the requested or default
      accounting method and eligible allowance account, and choose a batch.
    anchor: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:createWriteOff
    seam: sync
    on_failure: Reject the command and undo its transaction.
    left_inconsistent: The complete transaction is undone.
    observer: The API response reports the outcome and applicable refusal code.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:createWriteOff;
      services-accounting:modules/transactions/tests/integration/services/write-offs/write-offs.integration.spec.js#it
      takes the unit’s default_write_off_method (direct) when the request names
      none
  - 'n': 2
    actor_or_service: Write-off ledger trigger
    action: >-
      Insert bounded abandonment lines and derive the resulting line and invoice
      financial states.
    anchor: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:createWriteOff
    seam: sync
    on_failure: Reject abandonment beyond the remaining debt without effects.
    left_inconsistent: The complete transaction is undone.
    observer: The API response reports the outcome and applicable refusal code.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:createWriteOff;
      services-accounting:modules/transactions/tests/integration/services/write-offs/write-offs.integration.spec.js#it
      writes nothing: no write-off, no ledger line, no fact, no event
  - 'n': 3
    actor_or_service: Write-off reversal
    action: >-
      Restore the original value through a new numbered opposite write-off dated
      today, retaining the reversed original.
    anchor: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:reverseWriteOff
    seam: sync
    on_failure: Reject reversal of an already restored write-off.
    left_inconsistent: The complete transaction is undone.
    observer: The API response reports the outcome and applicable refusal code.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/write-offs/write-off-commands.ts:reverseWriteOff;
      services-accounting:modules/transactions/tests/integration/services/write-offs/write-offs.integration.spec.js#it
      answers the reversal: a second write-off, numbered next, its lines
      negating the first’s
idempotency: Abandonment and restoration each retain their own keyed result.
concurrency: >-
  Invoice-ledger locks coordinate write-off effects with collection against the
  same debt.
branches:
  - >-
    Restoration must precede applying money to debt whose write-off still
    stands.
waits: []
evidence:
  - >-
    services-accounting at f47cb263: services/write-offs/write-off-commands.ts;
    docs/debt/write-off-second-person-approval-deferred.md.
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-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-PI-005, TC-AI-005, TC-PRV-001, TC-PRV-002]
---
# Write off a balance and restore it

## What It Does

Write-off records the decision to abandon debt, while reversal preserves the explanation of its later restoration.

## The Flow

```mermaid
flowchart TD
  h0["Write-off commands"]
  h1["Write-off ledger trigger"]
  h0 --> h1
  h2["Write-off reversal"]
  h1 --> h2
```

The numbered hops identify the participating services, synchronization boundary and evidence. Branch conditions in the frontmatter explain where preparation, completion and recovery diverge.

## When Something Fails

Each hop records its rollback, retry or compensation boundary and the result visible to callers or operators. External outcomes can remain unresolved after local preparation commits; the listed recovery behavior defines what remains pending.

## Open Design Questions

The unresolved matters are recorded in the module findings; this workflow does not establish additional product approval.