--- id: DOM-COM-ORD-005 title: After-Sale Change realises: CON-COM-ORD-005 product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-ORD-orders readable_by: - SVC-COM-ORD-purchasing - SVC-PFM-QRY-data-exports custom_fields: none identity: >- Each cancellation, amendment or return has a time-ordered identity and a workspace number. A return authorization receives its own number, and a change order references its originating amendment. attributes: - name: document kind kind: enum required: true computed: false notes: >- Cancellation reverses line quantities; amendments alter a purchase or add a later offer; returns receive delivered goods. - name: order and lines kind: collection required: true computed: false notes: >- The targeted sale and affected quantities accompany application advice, outcomes, charges and line occupancy. - name: requester and authority kind: enum required: true computed: false notes: >- Caller classification and self-service, staff or override authority; administrative overrides require an explanation. - name: reason kind: text required: false computed: false notes: Optional requester reason code and explanation. - name: status kind: enum required: true computed: false notes: Each document kind has its own status map and transition explanation. - name: evaluated plan kind: collection required: true computed: false notes: >- Evaluation records credit caps, estimated refunds, charges, approval needs and blockers; cancellation and amendment plans are rechecked after thirty minutes. - name: financial treatment kind: enum required: true computed: false notes: >- Cancellation can refund, credit or omit settlement and normally waits for domain reversal; amendment and return policies determine their own settlement action and timing. - name: change order and effective date kind: reference required: false computed: false notes: >- A regular amendment may link a replacement order and schedule its effect immediately, at renewal or for a date. - name: return policy snapshot kind: collection required: false computed: false notes: >- The return stores resolved window, final-sale, allowance, approval, fee, shipping, label, settlement and disposition terms. - name: return authorization kind: collection required: false computed: false notes: >- The customer-facing authorization records a number, deadline, instructions, label treatment and receipt state; only one can remain open. - name: approvals and timing kind: date required: false computed: false notes: Approval attribution and timestamps for execution and completion. - name: financial adjustment kind: reference required: false computed: false notes: A reference to the fulfilment-owned settlement plan. - name: return policies kind: collection required: false computed: false notes: >- Scoped configured return terms and activity; the built-in policy fills missing configuration. relationships: - to: DOM-COM-ORD-002 cardinality: >- A document targets one sale and selected lines; an ordinary amendment can create one replacement sale. ownership: >- Orders persistence owns quantity and state writes while the document retains evaluated intent. cross_service: false - to: DOM-COM-ORD-003 cardinality: >- Affected lines obtain product-specific advice and reversal from their seller. ownership: Commerce owns the request while the seller owns domain reversal. cross_service: false - to: DOM-COM-ORD-004 cardinality: Cancellation requests revocation of active benefits on affected lines. ownership: Entitlements performs revocation at its own boundary. cross_service: false - to: DOM-COM-ORD-006 cardinality: Returned stock can restore the acquisition cost originally relieved. ownership: Purchasing records restored value during the receiving transaction. cross_service: false - to: DOM-ACC-TRX-001 cardinality: >- Settlement can create memos and charge invoices tied to the sale's financial documents. ownership: Accounting retains ownership of financial documents and money movement. cross_service: true invariants: - id: INV-DOM-COM-ORD-005-01 statement: >- Each order line can participate in one live document of each change kind; terminal documents release that occupancy. enforced_at: - database - service provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#holds staff’s request for approval (participant_requires_approval) and refuses a second request on the line 409 line_already_cancelling (B38); services-commerce:modules/orders/db/cancellation-lines.table.ts:cancellation_lines_active_uidx; services-commerce:modules/orders/db/amendment-lines.table.ts:amendment_lines_active_uidx; services-commerce:modules/orders/db/return-lines.table.ts:return_lines_active_uidx - id: INV-DOM-COM-ORD-005-02 statement: Administrative overrides require a recorded explanation. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/cancellations.table.ts:cancellations_override_reason_check; modules/orders/db/amendments.table.ts:amendments_override_reason_check; modules/orders/db/returns.table.ts:returns_override_reason_check - id: INV-DOM-COM-ORD-005-03 statement: >- Cancellation and ordinary amendments require acceptance; returns also admit closed orders, while after-sale promotions admit placed or accepted orders. enforced_at: - service provenance: observed source: >- services-commerce:modules/orders/services/cancellations/cancellation-workflow.ts:requestCancellation; services-commerce:modules/orders/services/amendments/amendment-workflow.ts:requestAmendment; services-commerce:modules/orders/services/returns/return-workflow.ts:requestReturn; services-commerce:modules/orders/services/amendments/promotion-amendment.ts - id: INV-DOM-COM-ORD-005-04 statement: >- The service checks each document kind's transition map and does not reopen terminal documents. enforced_at: - service provenance: observed source: >- services-commerce:modules/orders/services/persistence/cancellations.ts:CANCELLATION_TRANSITIONS; modules/orders/services/persistence/amendments.ts:AMENDMENT_TRANSITIONS; modules/orders/services/persistence/returns.ts:RETURN_TRANSITIONS - id: INV-DOM-COM-ORD-005-05 statement: >- Cancellation credit is capped by the remaining creditable invoice-line position. enforced_at: - service provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#credits no more than the invoice line still owes, so Accounting does not refuse the memo as an over-application - id: INV-DOM-COM-ORD-005-06 statement: >- Return policies are unique per scope, and only the workspace default omits a scope reference. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/return-policies.table.ts:return_policies_scope_uq, return_policies_scope_check - id: INV-DOM-COM-ORD-005-07 statement: >- A return can have only one authorization that is open or partially received. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/return-authorizations.table.ts:return_authorizations_open_uidx - id: INV-DOM-COM-ORD-005-08 statement: >- Return evaluation stores the resolved policy on the document, insulating it from later policy edits or deletion. enforced_at: - service provenance: observed source: >- services-commerce:modules/orders/services/returns/return-workflow.ts; services-commerce:modules/orders/services/persistence/returns.ts:recordReturnEvaluation - id: INV-DOM-COM-ORD-005-09 statement: >- Cancellation settlement normally follows the application's reversal; a policy may instead release money after fencing. enforced_at: - service provenance: test source: >- services-commerce:modules/orders/tests/e2e/cancellations.e2e.spec.js#is delivered by the worker to the participant’s cancel, which settles the document completed and runs the refund after the domain (ADR-13) - id: INV-DOM-COM-ORD-005-10 statement: >- Application operations retain after-sale documents; workspace removal is their deletion boundary. enforced_at: - service provenance: observed source: 'services-commerce:modules/orders/services/persistence/cancellations.ts' physical: - cancellations - cancellation_lines - amendments - amendment_lines - returns - return_lines - return_authorizations - return_policies evidence: - >- services-commerce at c8b66a98: modules/orders/db/cancellations.table.ts, cancellation-lines.table.ts, amendments.table.ts, amendment-lines.table.ts, returns.table.ts, return-lines.table.ts, return-authorizations.table.ts, return-policies.table.ts, post-purchase-values.ts; services/cancellations/*.ts; services/amendments/*.ts; services/returns/*.ts; services/persistence/{cancellations,amendments,returns,return-policies}.ts; aws/api/post-purchase.routes.ts; export/post-purchase.dataset.ts. - >- react-console at baf6dae3: lib/commerce/order-flows/live.ts (cancellation preview and confirmation). --- # After-Sale Change ## What It Models After-sale documents record cancellation, purchase amendment and goods return. Each preserves the request, authority and evaluated outcome while coordinating product work and financial settlement. Later promotion application uses an amendment document, and return-policy configuration belongs to this concept. ## Identity and Attributes The document kinds share party attribution, affected lines, approval information and settlement plans. Amendments add replacement-order and effective-date details; returns add policy snapshots and authorizations. Cancellation and amendment execution rechecks an aged plan rather than relying indefinitely on its first evaluation. ## Relationships Orders persistence changes purchased quantities and successor links. Applications perform product-specific reversal or modification; entitlement revocation and stock-cost restoration use their owning modules. Accounting records the financial documents produced by settlement. ## Invariants A partial unique index protects each document kind's live occupancy of a line. Override reasons and scoped policies have database checks. Eligibility differs by operation: ordinary cancellation and amendment require acceptance, returns also admit closed orders, and later promotions can target placed orders. Settlement checks credit caps and the configured domain-before-money policy. ## How It Is Stored and Shared Orders owns change documents and return terms. Fulfilment owns the obligations, adjustments and intervention logs they create. Local history and intervention rows preserve committed actions; Platform audit delivery remains incomplete. Export is provided without custom fields. ## Open Design Questions Scheduled amendments and overdue authorizations lack automated progression. Acceptance can leave an amendment awaiting payment when its follow-up fails. Cancellation preview leaves a real request, and the order-fee refund policy still needs a product answer.