--- id: WF-COM-ORD-011 title: Amend a purchase through a change order trigger: A caller requests a change to an eligible original purchase. product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b implements: - CAP-COM-ORD-015 - CAP-COM-ORD-005 - CAP-COM-ORD-006 - CAP-COM-ORD-007 moves: - STATE-COM-ORD-010 - STATE-COM-ORD-004 - STATE-COM-ORD-003 crosses: - SVC-COM-ORD-orders - SVC-COM-ORD-participants - SVC-ACC-TRX-transactions idempotency: >- The amendment reference identifies its single replacement sale; execution rejects documents that already progressed. Financial steps and payment attempts preserve their keys. concurrency: >- Live amendment occupancy excludes another amendment on the line. Transactional fencing and replacement claims protect execution; settlement requires executing and does not repair a failed acceptance hand-off. hops: - 'n': 1 actor_or_service: Orders route action: >- Authorize an accepted original item purchase, obtain seller change advice and calculate replacement price, proration, minimum fees and taxes for the effective date. anchor: 'services-commerce:modules/orders/services/amendments/amendment-workflow.ts:requestAmendment' seam: sync on_failure: Invalid targets or authority refuse; seller denial records rejection without changing the original line. left_inconsistent: No replacement sale commits from the refused plan. observer: Observed through the requester. provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#refuses a change order itself (409 order_not_amendable), an unknown product (409 product_not_found), another member, a reader and another tenant - 'n': 2 actor_or_service: Change transaction action: >- Atomically create the replacement sale with original parties and policy, commit replacement resources, fence the original, link successor and modification obligation, and begin execution. anchor: 'services-commerce:modules/orders/services/amendments/amendment-workflow.ts:executeAmendment' seam: sync on_failure: Claim or fence conflict rolls back and leaves the request prepared. left_inconsistent: No partial replacement transaction commits. observer: Observed through the requester; history on both orders. provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#marked the original line amended with its successor (nothing to fence: the type claims nothing), and wrote a modify obligation superseding the delivered fulfilment - 'n': 3 actor_or_service: Billing and adjustment action: >- Bill the replacement and settle unused original value into its invoice, then accept covered terms or credit amounts or wait for payment. anchor: 'services-commerce:modules/orders/services/amendments/amendment-settlement.ts' seam: sync on_failure: 'Missing billing waits for recovery, while adjustment failures create resumable exceptions.' left_inconsistent: The original can be marked amended while the replacement is unbilled or unpaid. observer: Observed through sale history; exceptions. provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#credited the unused value from the original payment and applied it to the change invoice; the document awaits the buyer’s tender - 'n': 4 actor_or_service: Buyer action: Collect any remaining replacement payment through the regular tender path. anchor: 'services-commerce:modules/orders/services/tender/tender-order.ts:tenderOrder' seam: sync on_failure: >- Payment retains its usual refusal and uncertainty behavior; deadline void restores the original and voids the amendment. left_inconsistent: The outstanding payment retains the payment flow's uncertainty. observer: Observed through the buyer. provenance: observed source: 'services-commerce:modules/orders/services/amendments/amendment-settlement.ts:onChangeOrderVoided' - 'n': 5 actor_or_service: Acceptance follow-up action: 'Resume an awaiting amendment when its replacement order is accepted, then attempt settlement.' anchor: 'services-commerce:modules/orders/services/amendments/amendment-settlement.ts:onChangeOrderAccepted' seam: sync on_failure: Failure is logged without an automatic retry of this hand-off. left_inconsistent: A paid replacement can leave its amendment awaiting tender. observer: Observed through only the function log exposes this outcome. provenance: observed source: 'services-commerce:modules/orders/services/orders/accept-order.ts:acceptOrder' - 'n': 6 actor_or_service: Delivery register worker (fulfilment module) action: Deliver seller modification or replacement and reevaluate amendment completion. anchor: >- services-commerce:modules/orders/services/amendments/amendment-settlement.ts:settleAmendmentAfterObligation seam: queue on_failure: Failed delivery concludes with exceptions. left_inconsistent: The original delivery can remain unsuperseded. observer: Observed through observed through fulfilment card; exceptions. provenance: test source: >- services-commerce:modules/orders/tests/e2e/amendments.e2e.spec.js#completes once the buyer’s card accepts the change order and the worker delivers the modify: the original fulfilment superseded branches: - A reduction can credit or refund the difference and accept its change sale without collection. - 'Deferred amendments retain their effective timing, but no current executor applies them later.' waits: - 'Approval, change-sale collection and seller execution can each suspend progress.' evidence: - >- services-commerce at c8b66a98: modules/orders/services/amendments/*.ts; services/orders/accept-order.ts; tests/e2e/amendments.e2e.spec.js; modules/operations/services/reconciler/reconciler.ts (scheduled amendments waiting). 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-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, 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] --- # Amend a purchase through a change order ## What It Does A regular amendment values the unused original purchase and its proposed replacement, then creates a linked change order. Product modification and Accounting settlement complete the change after any extra payment. ## The Flow ```mermaid sequenceDiagram participant R as Requester participant O as Orders participant A as Selling application participant X as Accounting participant W as Register worker R->>O: request change O->>A: change advice; price replacement; prorate R->>O: execute O->>A: one transaction: change order, new claims, fence original, change obligation O->>X: bill change order; memo unused value; apply credit R->>O: pay change order (if owed) O->>O: change order accepted, amendment executing W->>A: modify or replace O->>O: settle, original superseded ``` ## When Something Fails Execution is transactional, but later work is carried forward. Replacement deadline void restores the original line. Acceptance's unretired follow-up can leave the amendment awaiting payment after the replacement is paid, and future-effective changes have no automatic executor. ## Open Design Questions Live amendment choices are absent from the console. Scheduled execution and acceptance recovery need defined implementations.