---
id: WF-ACC-TRX-014
title: Share receivable facts with Commerce
trigger: >-
  Committed financial facts enter shared change-event delivery, nudged after
  successful transaction writes.
product_area: accounting
module: transactions
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-accounting: f47cb263875bbc0c5640fba7dae6785ec32695f8
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
implements:
  - CAP-ACC-TRX-020
moves: []
crosses:
  - SVC-ACC-TRX-transactions
hops:
  - 'n': 1
    actor_or_service: Change-event capture
    action: >-
      Capture each new receivable fact within the originating financial
      transaction.
    anchor: >-
      services-accounting:aws/accounting.change-events.ts:accountingChangeEventStreams
    seam: sync
    on_failure: Capture failure undoes the originating financial command.
    left_inconsistent: The complete transaction is undone.
    observer: The API response reports the outcome and applicable refusal code.
    provenance: documented
    source: 'services-accounting:docs/accounting/change-events.md#Change events'
  - 'n': 2
    actor_or_service: Change-event dispatcher
    action: >-
      Dispatch captured work on schedule or nudge through the registered shared
      queue handler.
    anchor: >-
      services-accounting:aws/accounting.change-events.ts:accountingChangeEventStreams
    seam: queue
    on_failure: Retain captured events for another dispatch attempt.
    left_inconsistent: Commerce's financial position may lag Accounting.
    observer: Dispatch diagnostics record delayed delivery.
    provenance: documented
    source: 'services-accounting:docs/accounting/change-events.md#Change events'
  - 'n': 3
    actor_or_service: Commerce financial facts handler
    action: >-
      Deliver captured facts in batches of up to one hundred, or log and
      acknowledge the batch when no receiver is configured.
    anchor: >-
      services-accounting:modules/transactions/services/change-events/commerce-financial-facts.ts:commerceFinancialFactsHandler
    seam: event
    on_failure: >-
      Configured delivery failures use queue retries and eventually dead-letter
      handling.
    left_inconsistent: >-
      Commerce may stay stale; available reconstruction data does not prove an
      implemented rebuild.
    observer: >-
      Handler diagnostics and dead-letter work expose exhausted delivery
      attempts.
    provenance: observed
    source: >-
      services-accounting:modules/transactions/services/change-events/commerce-financial-facts.ts:commerceFinancialFactsHandler
idempotency: >-
  Change-event delivery can repeat, requiring the receiver to handle duplicate
  facts.
concurrency: >-
  Facts are retained insertions; delivery order across different commands is not
  a guaranteed financial ordering.
branches: []
waits: []
evidence:
  - >-
    services-accounting at f47cb263: aws/accounting.change-events.ts;
    services/change-events/commerce-financial-facts.ts;
    aws/logic/transactions-api.lambda.ts (the dispatcher nudge);
    docs/accounting/change-events.md.
controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, 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-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-001, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004]
---
# Share receivable facts with Commerce

## What It Does

Financial sharing is asynchronous and receiver configuration controls whether Commerce is actually called. Acknowledging an unconfigured batch leaves reconstruction as a separate concern.

## The Flow

```mermaid
flowchart TD
  h0["Change-event capture"]
  h1["Change-event dispatcher"]
  h0 --> h1
  h2["Commerce financial facts handler"]
  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

A working Commerce reconstruction path and agreement of its position view with receivable facts remain unproved.