---
id: STATE-COM-FUL-008
title: Return receipt lifecycle
object: DOM-COM-FUL-004
product_area: commerce
module: fulfillment
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
source_sha:
  services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b
states:
  - name: received
    meaning: Authorized incoming quantities are retained without changing stock.
  - name: inspected
    meaning: The receipt’s received lines have retained inspection results.
  - name: dispositioned
    meaning: All received units have retained physical disposition results.
transitions:
  - from: received
    to: inspected
    trigger: Staff complete condition recording for received lines.
    guard: >-
      The receipt must not be dispositioned and every inspected line must use an
      accepted condition.
    side_effects:
      - Start inspection on the associated return document.
    who: Warehouse staff (return receipt update)
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/returns/return-receiving.ts:inspectReturnReceipt
  - from: received
    to: dispositioned
    trigger: Staff retain physical outcomes for all received units.
    guard: >-
      Disposition must fit received quantities and policy, without the
      unsupported replacement choice.
    side_effects:
      - >-
        Restore original cost for restocking; write quarantine movements without
        cost restoration.
      - >-
        Finalize return disposition locally, then continue financial work and
        document completion after commit.
    who: Warehouse staff
    provenance: observed
    source: >-
      services-commerce:modules/shipping/services/returns/return-receiving.ts:dispositionReturnReceipt
  - from: inspected
    to: dispositioned
    trigger: Staff retain physical outcomes for all received units.
    guard: >-
      Disposition must fit received quantities and policy, without the
      unsupported replacement choice.
    side_effects:
      - >-
        Apply the same explicitly described disposition effects as the preceding
        disposition edge.
    who: Warehouse staff
    provenance: test
    source: >-
      services-commerce:modules/shipping/tests/integration/services/returns/return-receiving.integration.spec.js#restocks
      the two units at the bin they shipped from: the return_restock movement
      naming the disposition, on hand up two, the two reliefs reversed at 1500
      with the restore_cogs fact of 3000
invalid:
  - from: dispositioned
    to: received
    why: Final disposition refuses further receipt edits or inspection.
  - from: dispositioned
    to: inspected
    why: Final disposition refuses further receipt edits or inspection.
concurrency: >-
  Receipt and disposition operations lock their receiving record and retain
  return quantities together. Financial continuation begins after those local
  commits.
invariants:
  - INV-DOM-COM-FUL-004-09
evidence:
  - >-
    services-commerce at c8b66a98: modules/shipping/db/return-receipts.table.ts,
    return-receipt-lines.table.ts, return-dispositions.table.ts;
    services/returns/return-receiving.ts;
    modules/orders/services/returns/return-workflow.ts.
---

# Return Receipt Lifecycle

## The Lifecycle

```mermaid
stateDiagram-v2
  [*] --> received: goods counted
  received --> inspected
  received --> dispositioned
  inspected --> dispositioned
  dispositioned --> [*]
```

## Transitions Explained

Receiving counts goods against the return authorization and moves no stock. Inspection records condition; disposition can proceed without a separate inspection. Restock restores original cost, while quarantine writes unavailable stock without restoring cost.

## What Cannot Happen

Receipt keys prevent duplicate receiving and terminal disposition refuses further inspection or disposition. Quantity constraints prevent disposition beyond the recorded receipt.

## Concurrency and Timing

Warehouse records and return quantities commit before financial continuation. Failed money work has no automatic retry on receipt replay or repeated disposition.