--- id: SVC-COM-ORD-orders title: Orders Service Module product_area: commerce module: orders repository: services-commerce source_module: modules/orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-ORD-002 - DOM-COM-ORD-005 does_not_own: - >- Accounting retains financial documents, schedules and financial position; Commerce retains processing requests and projections. - >- Fulfilment retains delivery, adjustments, exceptions, interventions, enforcement and financial-fact handling. - 'Catalog retains policies and offers, including redemption release.' - Data operations retains its own job routes even when hosted by the order function. operations: - operation_id: getOrdersHealth intent: Expose orders runtime health and build information without customer records. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: runtime status is outside submission processing.' - operation_id: listOrders intent: >- Retrieve permitted sales newest first, using number or buyer search and status, money, kind, policy and date filters; pages default to fifty and cap at two hundred. access: portal permission: commerce.orders.read realises: - CAP-COM-ORD-010 - CAP-COM-ORD-011 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: getOrder intent: >- Retrieve the purchase with its lines, frozen details, attempts, invoices, delivery obligations and history. access: portal permission: commerce.orders.read realises: - CAP-COM-ORD-010 - CAP-COM-ORD-011 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: getOrderInstallmentSchedule intent: >- Retrieve the plan and schedule explanation, also retrying missing schedule creation and linking issued installment invoices. access: portal permission: commerce.orders.read realises: - CAP-COM-ORD-009 published_to_submissions: 'not published: schedule retrieval can perform recovery writes and has no submission-stage contract.' - operation_id: voidOrder intent: End a placed sale through a reasoned staff intervention under a required request key. access: console permission: commerce.orders.void realises: - CAP-COM-ORD-008 published_to_submissions: 'not published: ending an unaccepted sale is an administrative intervention.' - operation_id: tenderOrder intent: >- Process keyed payment by card, bank, offline, credit, terms or installment, resuming unresolved attempts. access: portal permission: commerce.orders.tender realises: - CAP-COM-ORD-007 - CAP-COM-ORD-009 - CAP-COM-ORD-006 published_to_submissions: 'not published: financial collection requires a payment instrument and has no submitting-stage binding.' - operation_id: requestCancellation intent: >- Create and evaluate a keyed cancellation, optionally executing it; administrative override requires its permission and explanation. access: portal permission: commerce.cancellations.create (evaluates commerce.cancellations.override) realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: existing-sale changes have no submission-stage binding.' - operation_id: listCancellations intent: Retrieve a sale's cancellation documents in reverse time order. access: portal permission: commerce.cancellations.read realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: getCancellation intent: Retrieve the cancellation's calculated plan and affected lines. access: portal permission: commerce.cancellations.read realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: executeCancellation intent: Run an approved cancellation after rechecking aged evaluation. access: portal permission: commerce.cancellations.create realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: withdrawCancellation intent: End an unexecuted cancellation and release line occupancy. access: portal permission: commerce.cancellations.update realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: approveCancellation intent: Authorize a waiting cancellation with a recorded staff explanation. access: console permission: commerce.cancellations.approve realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: rejectCancellation intent: Refuse a cancellation with a recorded staff explanation. access: console permission: commerce.cancellations.approve realises: - CAP-COM-ORD-014 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: requestAmendment intent: 'Create and evaluate a keyed change to an accepted original purchase, optionally proceeding to execution.' access: portal permission: commerce.amendments.create (evaluates commerce.amendments.override) realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: listAmendments intent: Retrieve a sale's amendment documents in reverse time order. access: portal permission: commerce.amendments.read realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: getAmendment intent: Retrieve the amendment's calculated plan and affected lines. access: portal permission: commerce.amendments.read realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: executeAmendment intent: Run an approved amendment and create its replacement order. access: portal permission: commerce.amendments.create realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: withdrawAmendment intent: End an amendment before replacement execution begins. access: portal permission: commerce.amendments.update realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: approveAmendment intent: Authorize a waiting amendment with a recorded explanation. access: console permission: commerce.amendments.approve realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: rejectAmendment intent: Refuse an amendment with a recorded explanation. access: console permission: commerce.amendments.approve realises: - CAP-COM-ORD-015 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: applyPromotionToOrder intent: >- Apply a later offer to a placed or accepted sale with a reason and required request key, crediting its discount. access: console permission: commerce.amendments.apply-promotion realises: - CAP-COM-ORD-015 - CAP-COM-ORD-004 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: requestReturn intent: >- Create a keyed request to return delivered quantities from an accepted or closed sale, authorizing eligible quantities immediately. access: portal permission: commerce.returns.create (evaluates commerce.returns.override) realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: listReturns intent: Retrieve a sale's return documents in reverse time order. access: portal permission: commerce.returns.read realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: getReturn intent: Retrieve return quantities and authorization details. access: portal permission: commerce.returns.read realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: retrieval has no submission-stage binding.' - operation_id: withdrawReturn intent: End a return before any receipt has occurred. access: portal permission: commerce.returns.update realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: subsequent sale changes have no submission-stage binding.' - operation_id: approveReturn intent: Authorize an exceptional return with a recorded explanation. access: console permission: commerce.returns.approve realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: rejectReturn intent: Refuse a return with a recorded explanation. access: console permission: commerce.returns.approve realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: administrative correction has no submission-stage binding.' - operation_id: createReturnPolicy intent: 'Configure scoped return terms for a product, store or workspace default.' access: console permission: commerce.return-policies.create realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: policy administration has no submission-stage binding.' - operation_id: listReturnPolicies intent: Retrieve configured return terms by name with pagination. access: console permission: commerce.return-policies.read realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: policy retrieval has no submission-stage binding.' - operation_id: getReturnPolicy intent: Retrieve one configured return policy. access: console permission: commerce.return-policies.read realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: policy retrieval has no submission-stage binding.' - operation_id: deleteReturnPolicy intent: Remove configured terms without changing the snapshots on evaluated returns. access: console permission: commerce.return-policies.delete realises: - CAP-COM-ORD-016 published_to_submissions: 'not published: policy administration has no submission-stage binding.' events: - name: >- order history events (placed, billed, repriced to invoice, tender recorded and resolved, transitioned, claims released, claim confirmed and unconfirmed, promotion applied and released, void refund planned, billing voided, installment schedule created and deferred, lines cancelled and returned, line amended and restored, amendment, cancellation and return events, intervention, financial fact, entitlements granted, revoked and reinstated) direction: produced when: 'Sale transitions, financial replies, collection outcomes and subsequent changes append history.' payload_summary: 'The sale keeps attributed, correlated and timed action details in its own append-only trail.' - name: Accounting receivable change events direction: consumed when: Fulfilment receives Accounting facts about money applied to invoice lines. payload_summary: >- Document and line references, financial categories and amounts support adjustment recovery and projection refresh. - name: commerce.intervention audit event direction: produced when: 'Successful staff voids, decisions and offer applications request intervention auditing.' payload_summary: 'The default stand-in receives subject, attribution and local intervention references.' jobs: - name: 'tender-window, financial (billing, uncertain payments, mirrors) and hold passes' schedule: every minute inside the checkout sweeper function purpose: >- Recover overdue unpaid sales, invoice requests, uncertain collections, monetary projections, installment arrangements and resource leases. integrations: - system: Accounting direction: outbound contract: >- Configured Accounting transport supports invoices, collections, reversals and tax; financial position is also read from its line-position view. - system: Selling applications direction: outbound contract: >- Shared seller contracts support preparation, lease confirmation and change advice, with transactional database functions for claims and fencing. - system: Platform audit direction: outbound contract: Intervention auditing awaits the Platform writer; the current provider is a stand-in. - system: Workspace data export direction: outbound contract: 'Query exposure supplies sale, history and subsequent-change datasets.' consistency: - rule: 'Placement commits sale, claims, offer uses, obligations and cart completion atomically.' kind: transactional compensation: Any transaction failure removes the entire attempted placement. - rule: 'Remote billing, payment and schedule requests follow domain commit under stable keys.' kind: eventual compensation: Recovery passes or later requests resume known work; deferred invoice deletion lacks recovery. - rule: 'Post-acceptance gate, mirror and amendment work cannot reverse acceptance.' kind: eventual compensation: 'Register and financial passes recover supported work, but amendment progression is not retried.' - rule: 'Void commits resource release, stopped delivery, returned offer uses and settlement intent together.' kind: transactional compensation: Financial reversal follows through the adjustment worker and exceptions. - rule: Change execution commits domain intent before remote reversal and settlement complete. kind: eventual compensation: Worker retry and confirmation resume work; terminal failures can finish with exceptions. - rule: The financial projection reflects the last successful Accounting derivation. kind: eventual compensation: Received facts and timed refresh provide later updates. evidence: - >- services-commerce at c8b66a98: modules/orders/aws/api/orders.routes.ts, tenders.routes.ts, post-purchase.routes.ts (route declarations), *.schemas.ts, *-api-mapper.ts; aws/orders.module.ts; services/**; db/*.table.ts; export/*.dataset.ts; metadata/orders.object.ts; aws/commerce.service.ts (OrdersPermissions, CancellationsPermissions, AmendmentsPermissions, ReturnsPermissions, ReturnPoliciesPermissions). 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-CRY-002, TC-CRY-003, 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-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Orders Service Module ## What This Service Is For Orders retains placed purchases and coordinates billing, payments and later changes. Staff use it to inspect sales, collect outstanding money, void unaccepted purchases and manage cancellations, amendments and returns. ## Boundary The module owns sales and change documents. Accounting owns the financial ledger, while Commerce stores links, requests and projections. Fulfilment owns delivery obligations, adjustments, exceptions and intervention records. Sellers retain their product work and resource claims. ## Operations in Words Reads expose sale lists, complete purchase detail and installment schedules. Payment resumes outstanding attempts, and staff voids require an explanation. Change documents support request, evaluation, execution and authorized decisions; returns progress through receiving rather than an execute route. Staff can add later offers or manage return-policy configuration. No operation is published to Submissions. ## Events and Jobs Order events retain local business history. Delegated Accounting-fact handling resumes gates, settlement and projection updates. Staff audit messages currently use incomplete transport. Timed reservation, deadline and financial work runs in the checkout-owned schedule. ## Consistency Guarantees Placement and domain execution use shared transactions with application claim functions. Remote financial and delivery work happens separately and recovers through stable keys, workers and exceptions. Deferred invoice deletion and amendment acceptance remain gaps in automatic recovery.