--- id: CAP-COM-FUL-006 title: Handle financial reversals after delivery feature: FEAT-COM-FUL-02 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-REG-019 - CAP-COM-REG-024 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: - >- services-commerce:docs/migrations/operations/README.md#Section 5 walkthrough (decisions E and F, Andrew 2026-10-18) purpose: >- Commerce tracks the response required when a delivered sale loses its financial backing. outcomes: - Reversal of a delivered purchase has a recorded response. - Withdrawal of delivery follows the policy or an authorized human decision. concepts: - CON-COM-FUL-001 - CON-COM-FUL-003 actors: - ACT-COM-012 - ACT-COM-011 - ACT-COM-008 surfaces: - job - api preconditions: [] postconditions: [] permissions: - key: commerce.enforcements.read where_checked: api scope: tenant - key: commerce.enforcements.resolve where_checked: api scope: tenant rules: - id: BR-CAP-COM-FUL-006-01 proved_by: [ATS-COM-FUL-006-01, TST-COM-FUL-018, TST-COM-FUL-027] statement: >- Payment reversal or refund, dispute or chargeback opening and invoice reopening affect only the identified lines' delivered or in-progress obligations, leaving waiting obligations untouched. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates four enforcements: three dispatched (suspend, cancel_line, notify), one for a person (review); the none policy and the pending obligation get nothing origin: >- D-P5-01 (build decision, not a product ruling): services-commerce:docs/migrations/operations/README.md#D-P5-01 - id: BR-CAP-COM-FUL-006-02 proved_by: [ATS-COM-FUL-004-11, ATS-COM-FUL-006-01, ATS-COM-FUL-006-06, ATS-COM-FUL-008-08, TST-COM-FUL-018, TST-COM-FUL-027] statement: >- The default review response records enforcement and raises a staff-review exception without instructing the delivering application. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request origin: >- Decision E, Andrew 2026-10-18 (review by a person, as built): services-commerce:docs/migrations/operations/README.md#Section 5 walkthrough - id: BR-CAP-COM-FUL-006-03 proved_by: [ATS-COM-FUL-004-11, ATS-COM-FUL-006-01, ATS-COM-FUL-006-06, ATS-COM-FUL-008-08, TST-COM-FUL-018, TST-COM-FUL-027] statement: >- Notify and suspend responses immediately authorize and queue an unconditional enforcement obligation while retaining the original completed obligation. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#writes the suspend enforcement dispatched, with its enforce obligation authorized, queued and nudged, keyed on the fact origin: none - id: BR-CAP-COM-FUL-006-04 proved_by: [ATS-COM-FUL-006-01, TST-COM-FUL-018, TST-COM-FUL-027] statement: >- A cancel-line response sends the enforcement instruction and also raises a review for staff to complete cancellation and its financial consequences. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request origin: >- Decision F, Andrew 2026-10-18 (staff finish the money side, as built): services-commerce:docs/migrations/operations/README.md#Section 5 walkthrough; D-P5-02 - id: BR-CAP-COM-FUL-006-05 proved_by: [] statement: The none reversal response leaves the delivered line unchanged. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates four enforcements: three dispatched (suspend, cancel_line, notify), one for a person (review); the none policy and the pending obligation get nothing origin: none - id: BR-CAP-COM-FUL-006-06 proved_by: [ATS-COM-FUL-006-02, TST-COM-FUL-027] statement: >- A reversal without an explaining cancellation raises one informational refund-without-cancellation exception for each delivered order. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#raises refund_without_cancellation once per delivered order, and the enforcement_created line on each history origin: none - id: BR-CAP-COM-FUL-006-07 proved_by: [ATS-COM-FUL-006-03, TST-COM-FUL-018, TST-COM-FUL-025, TST-COM-FUL-027] statement: >- The same obligation and financial event produce at most one enforcement, including when the event is redelivered. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates nothing when the same fact is enforced again (idempotent on the event id) origin: none - id: BR-CAP-COM-FUL-006-08 proved_by: [ATS-COM-FUL-006-04, TST-COM-FUL-027, TST-COM-FUL-030] statement: >- Restored funds produce one restoration for each enforcement that acted, dispatching it where the application supports restoration and otherwise leaving it for staff. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#dispatches a restore for the suspended and the notified deliveries (the unlimited product declares one) and leaves the capacity product’s with staff origin: none - id: BR-CAP-COM-FUL-006-09 proved_by: [ATS-COM-FUL-006-04, TST-COM-FUL-027, TST-COM-FUL-030] statement: >- Enforcement accepts only its defined transitions through pending, dispatched, completed, restored, failed and resolved states. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/integration/services/persistence/enforcements.queries.integration.spec.js#moves an enforcement along its lifecycle (pending -> dispatched -> completed -> restored) and refuses a move it does not allow origin: none - id: BR-CAP-COM-FUL-006-10 proved_by: [ATS-COM-FUL-006-05, TST-COM-FUL-018, TST-COM-FUL-070] statement: >- Staff resolution requires a reason and resolution, closes the enforcement-review exception, and rejects readers and repeated resolution. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/enforcement.e2e.spec.js#resolves the seat’s review on its route with the reason and the resolution, refusing a reader and a repeat origin: none - id: BR-CAP-COM-FUL-006-11 proved_by: [] statement: >- Enforcement read authority permits lists by order or state and inspection of an individual enforcement. kind: permission enforced_at: - api must_prove: false provenance: observed source: 'services-commerce:modules/operations/aws/api/operations.routes.ts' origin: none scenarios: - id: SC-CAP-COM-FUL-006-01 given: >- An order's delivered membership, seat and shirt have different reversal settings. when: Apply the chargeback events. then: >- Membership suspension is dispatched while seat review and shirt-cancellation follow-up remain with staff. provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/enforcement.e2e.spec.js#answers succeeded for each event and enforces each: two dispatched (suspend, cancel_line), one for a person (review), the receipt saying so - id: SC-CAP-COM-FUL-006-02 given: Funds return after membership suspension. when: Apply Accounting's restored-funds event. then: >- The application restores membership and the enforcement reaches restored state. provenance: test source: >- services-commerce:modules/fulfillment/tests/e2e/enforcement.e2e.spec.js#restores the membership through a dispatched restore and closes the suspension as restored; the T-shirt’s restore stays with staff (no restore declared) edge_cases: [] constraints: [] depends_on: - CAP-COM-FUL-002 - CAP-COM-FUL-004 related: - CAP-COM-FUL-008 journeys: - JNY-COM-FUL-005 open_questions: [] evidence: - repository: services-commerce sources: - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates four enforcements: three dispatched (suspend, cancel_line, notify), one for a person (review); the none policy and the pending obligation get nothing - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#writes the suspend enforcement dispatched, with its enforce obligation authorized, queued and nudged, keyed on the fact - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#leaves the review enforcement pending with an enforcement_review exception and no obligation, and the cancel_line one dispatched with a review for the request - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates four enforcements: three dispatched (suspend, cancel_line, notify), one for a person (review); the none policy and the pending obligation get nothing - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#raises refund_without_cancellation once per delivered order, and the enforcement_created line on each history - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#creates nothing when the same fact is enforced again (idempotent on the event id) - >- services-commerce:modules/fulfillment/tests/integration/services/enforcement/enforcement-handler.integration.spec.js#dispatches a restore for the suspended and the notified deliveries (the unlimited product declares one) and leaves the capacity product’s with staff - >- services-commerce:modules/fulfillment/tests/integration/services/persistence/enforcements.queries.integration.spec.js#moves an enforcement along its lifecycle (pending -> dispatched -> completed -> restored) and refuses a move it does not allow - >- services-commerce:modules/fulfillment/tests/e2e/enforcement.e2e.spec.js#resolves the seat’s review on its route with the reason and the resolution, refusing a reader and a repeat - 'services-commerce:modules/operations/aws/api/operations.routes.ts' controls: [TC-IAM-006, 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-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-004, TC-MON-001, TC-MON-002, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-FUL-02-03, FAS-COM-FUL-02-04, FAS-COM-FUL-02-05] suites: [TST-COM-FUL-018, TST-COM-FUL-025, TST-COM-FUL-027, TST-COM-FUL-030, TST-COM-FUL-070] --- # Handle financial reversals after delivery ## Purpose Commerce tracks the response required when a delivered sale loses its financial backing. ## How It Works Accounting reports a reversal affecting sold lines. Commerce identifies deliveries that may require review or an application instruction. The frozen reversal setting determines which response is appropriate. Staff handle reviews and finish financial or cancellation work that cannot be delegated. Restored funds can lead to a corresponding restoration instruction where the application supports it. The enforcement record lets staff follow that work independently of the original delivery. The product should show the financial event, delivery consequence and remaining staff responsibility together. ## Relationships - Authorize delivery from current order facts supplies or consumes related delivery records. - Carry authorized work to its delivering application supplies or consumes related delivery records. - Review and resolve operations findings supplies or consumes related delivery records.