---
id: STATE-ACC-TRX-002
title: Credit and debit memo lifecycle
object: DOM-ACC-TRX-001
product_area: accounting
module: transactions
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
states:
  - name: not created
    meaning: The memo has not been created.
  - name: issued
    meaning: A numbered adjustment has been applied to billed lines.
  - name: void
    meaning: Opposite dated lines have cancelled the retained adjustment.
  - name: draft
    meaning: >-
      The vocabulary includes draft, but creation commands do not produce
      drafts.
transitions:
  - from: not created
    to: issued
    trigger: record a billing adjustment
    guard: >-
      The target must be a real issued invoice with its own lines, an open
      period and eligible batch; credits are limited to outstanding and
      releasable value.
    side_effects:
      - assign the memo number
      - insert adjustment ledger lines
      - release receipt money by descending allocation identity where needed
      - record tax adjustment
      - append financial facts and history
    who: >-
      Staff with the appropriate memo-create permission; Commerce can create
      credit memos through reversals.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/change-memos/memo-commands.ts;
      services-accounting:modules/transactions/services/payments/free-paid-money.ts;
      services-accounting:modules/transactions/db/credit-memos.table.ts;
      services-accounting:modules/transactions/db/debit-memos.table.ts;
      services-accounting:modules/transactions/tests/integration/services/change-memos/credit-memos.integration.spec.js#it
      answers the memo whole: issued, numbered from 1,000,000, its line and
      total, the invoice’s bill-to
  - from: issued
    to: issued
    trigger: correct metadata or batching
    guard: Batch moves and accounting-date changes require unposted batching.
    side_effects:
      - append date-correction facts where relevant
      - append history when the document changes
    who: Staff with the appropriate memo-update permission.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/change-memos/memo-commands.ts;
      services-accounting:modules/transactions/services/payments/free-paid-money.ts;
      services-accounting:modules/transactions/db/credit-memos.table.ts;
      services-accounting:modules/transactions/db/debit-memos.table.ts;
      services-accounting:modules/transactions/tests/integration/services/document-edits/reassign-and-edit.integration.spec.js#it
      negates the facts on the old accounting date and restates them on the new
      one, the originals untouched
  - from: issued
    to: void
    trigger: cancel the adjustment
    guard: >-
      A reason is required and debit cancellation cannot remove value already
      consumed by later adjustments.
    side_effects:
      - insert opposite adjustment lines
      - restore the billed position
      - append cancellation facts
    who: Staff with the appropriate memo-update permission.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/change-memos/memo-commands.ts;
      services-accounting:modules/transactions/services/payments/free-paid-money.ts;
      services-accounting:modules/transactions/db/credit-memos.table.ts;
      services-accounting:modules/transactions/db/debit-memos.table.ts;
      services-accounting:modules/transactions/tests/integration/services/change-memos/credit-memos.integration.spec.js#it
      returns the invoice’s balances to what they were before the memo
invalid:
  - from: void
    to: issued
    why: Cancelled memo history is retained without a reissue transition.
  - from: issued
    to: draft
    why: >-
      The service creates issued adjustments directly, without a preparation
      lifecycle.
  - from: draft
    to: issued
    why: >-
      No service command advances memo drafts despite the console editors
      expecting them.
concurrency: >-
  Statement-level ledger triggers take ordered document and receipt locks. A
  credit beyond the permitted value fails the financial bound and rolls back.
invariants:
  - INV-DOM-ACC-TRX-001-13
  - INV-DOM-ACC-TRX-001-14
evidence:
  - >-
    services-accounting at f47cb263: services/change-memos/memo-commands.ts;
    services/payments/free-paid-money.ts; db/document-vocabularies.ts (memo
    statuses); docs/architecture/accounting-2.0/02-decisions.md M1-4, M1-5, A-5.
---
# Credit and debit memo lifecycle

## The Lifecycle

Credit and debit memos use the same issue-and-void structure. The declared draft vocabulary is retained for transparency rather than presented as an available command path.

```mermaid
stateDiagram-v2
  direction LR
  state "not created" as s0
  state "issued" as s1
  state "void" as s2
  state "draft" as s3
  s0 --> s1 : record a billing adjustment
  s1 --> s1 : correct metadata or batching
  s1 --> s2 : cancel the adjustment
```

## Transitions Explained

The transition rows identify the initiating action, eligibility checks, resulting records and responsible caller. They retain the pinned evidence for each path.

## What Cannot Happen

The invalid-transition rows describe final-state protection and unsupported paths; command eligibility remains distinct from the declared state vocabulary.

## Concurrency and Timing

Statement-level ledger triggers take ordered document and receipt locks. A credit beyond the permitted value fails the financial bound and rolls back. Memo creation and cancellation are synchronous financial commands.