---
id: WF-ACC-REC-006
title: Split or write off a settlement item
trigger: Staff split an unclaimed effect or resolve money that will not arrive.
product_area: accounting
module: reconciliation
revision: 3
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
implements:
  - CAP-ACC-REC-007
  - CAP-ACC-REC-014
moves:
  - STATE-ACC-REC-004
  - STATE-ACC-REC-005
crosses:
  - SVC-ACC-REC-reconciliation
idempotency: >-
  Split and resolution use distinct request-key scopes. Matching repeats replay
  results; parts and write-off requests also have deterministic effect
  identities.
concurrency: >-
  Commands lock and compare the item version; write-off request creation
  share-locks the selected batch.
hops:
  - 'n': 1
    actor_or_service: Settlement item command
    action: >-
      Claim the request key and lock an unresolved, unheld item at the expected
      version.
    anchor: >-
      services-accounting:modules/reconciliation/services/settlement-items/settlement-item-commands.ts
    seam: sync
    on_failure: Refuse invalid state or version and release a failed claim.
    left_inconsistent: The outstanding item remains unchanged.
    observer: The response can name the competing holder.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:splitSettlementItem
  - 'n': 2
    actor_or_service: Split
    action: >-
      Mark the original split and insert documented parts that sum to it with
      the required sign.
    anchor: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:splitSettlementItem
    seam: sync
    on_failure: >-
      Service sign and total checks or deferred database checks abort invalid
      parts.
    left_inconsistent: Neither split resolution nor partial parts commit.
    observer: The response or retained part records show the result.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/db/settlement-items.table.ts:settlement_items_split_trigger
  - 'n': 3
    actor_or_service: Write-off
    action: >-
      For write-off, resolve the item and request opposite clearing and
      write-off lines according to amount sign.
    anchor: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem
    seam: sync
    on_failure: Missing account or accepting batch aborts the write-off.
    left_inconsistent: The amount stays outstanding.
    observer: The caller receives the setup refusal.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem
  - 'n': 4
    actor_or_service: Settlement item command
    action: >-
      Clear the original overdue concern, retain the financial event and
      complete the key.
    anchor: >-
      services-accounting:modules/reconciliation/services/persistence/reconciliation-exceptions.ts:clearExceptionsOf
    seam: sync
    on_failure: A write failure rolls back the entire command.
    left_inconsistent: No incomplete financial resolution persists.
    observer: History and enabled attention record the conclusion.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/settlement-items.ts:resolveSettlementItem
  - 'n': 5
    actor_or_service: Batch Management
    action: >-
      Batch Management consumes the write-off request during operational
      posting.
    anchor: 'services-accounting:modules/batches/services/engine/posting-documents.ts'
    seam: sync
    on_failure: A posting failure leaves the request pending.
    left_inconsistent: The resolved item can still lack its ledger effect.
    observer: Readiness identifies pending accounting.
    provenance: observed
    source: >-
      services-accounting:modules/reconciliation/services/persistence/reconciliation-ledger-postings.ts
branches:
  - Other resolution outcomes create no accounting request.
  - The current console has no split or write-off controls.
waits: []
evidence:
  - >-
    services-accounting at f47cb263:
    modules/reconciliation/services/persistence/settlement-items.ts;
    services/settlement-items/settlement-item-commands.ts;
    services/rules/posting-plans.ts; aws/api/outstanding.routes.ts.
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-DAT-001, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003]
---
# Split or write off a settlement item

## What It Does

Splitting lets separate payouts explain parts of one effect. Writing off permanently resolves missing money and requests its movement from clearing to the configured loss account.

## The Flow

```mermaid
sequenceDiagram
  participant F as Finance approver
  participant S as Settlement command
  participant D as Accounting database
  participant P as Batch Management
  F->>S: split or resolve (key, version, reason)
  S->>D: lock item, check unclaimed and unresolved
  alt split
    S->>D: mark split, insert parts
  else write-off
    S->>D: mark written off, ledger request in operational batch
  end
  S->>D: clear overdue blocker, event, stored answer
  P->>D: later, post the write-off request
```

## When Something Fails

The command’s item, parts or request, concern clearing and activity commit together. Ledger completion remains separate, and no implemented command reverses a mistaken write-off.

## Open Design Questions

The described un-write-off mechanism is absent. Screen support for split and write-off is also deferred.