--- id: DOM-COM-ORD-002 title: Order realises: CON-COM-ORD-002 product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b macroservice-libraries: 54536a441935c6e09fdb7f96f0bec71c52ba4e03 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owned_by: SVC-COM-ORD-orders readable_by: - SVC-COM-ORD-checkout - SVC-COM-ORD-entitlements - SVC-COM-ORD-purchasing - SVC-PFM-QRY-data-exports lifecycle: STATE-COM-ORD-004 custom_fields: none identity: >- Orders combine a time-ordered record identity with a positive workspace number displayed with the order prefix. Number allocation can leave gaps when placement fails. attributes: - name: number kind: number required: true computed: true notes: A positive number allocated from the workspace's Platform seed. - name: origin kind: reference required: false computed: false notes: >- The source cart, originating amendment for a change order, or legacy reference for an imported purchase. - name: frozen checkout policy kind: collection required: true computed: false notes: >- Placement captures the profile identity, version and resolution context with its payment, invoice, account and charge-product settings. - name: classification kind: computed required: true computed: true notes: >- Main-item classifications produce one kind, mixed when several apply and general when none apply; classification serves reporting. - name: parties kind: collection required: true computed: false notes: >- Party references and acting identities accompany billing and shipping address snapshots. - name: business unit and currency kind: reference required: true computed: false notes: The policy supplies the Accounting business unit and sale currency. - name: placed and accepted instants kind: date required: true computed: false notes: >- Placement supplies a common pricing timestamp; acceptance is optional until the payment requirement is satisfied. - name: status and reason kind: enum required: true computed: false notes: Sale status and the explanation recorded for its latest transition. - name: tender requirement and window kind: enum required: true computed: false notes: >- The policy selects pay now, deposit, terms or none; pay-now and deposit purchases also record a deadline. - name: billing state kind: enum required: true computed: false notes: 'Pending, billed or blocked, together with billing-attempt information.' - name: totals kind: money required: true computed: true notes: >- Minor-unit amounts for items, discounts, tax, shipping, fees and the resulting sale total. - name: lines kind: collection required: true computed: false notes: >- Purchased and charge lines retain price and audience explanations, discount shares, quantities, states, bundle and successor links, recipients and invoice-line references. - name: frozen purchase per item line kind: collection required: true computed: false notes: >- Each item keeps a protected snapshot of canonical details, schema, attestation, conditions, cancellation terms, delivery plan and committed resources. - name: payment attempts kind: collection required: false computed: false notes: >- Attempt sequences retain payment kind, amount, state, request key, outcome, account and token suffix; card details remain outside Commerce. - name: invoice links kind: collection required: false computed: false notes: >- Links identify sale, fee, installment and amendment invoices and their provisional origin. - name: hold and claim ledger kind: collection required: false computed: false notes: >- Reservations track application holds, claims and leases; the application's records govern actual resource ownership. - name: money mirror kind: computed required: false computed: true notes: >- A timestamped projection of Accounting's invoicing, payments, credits, refunds, write-offs, balance and optional schedule. - name: installment plan and schedule kind: reference required: false computed: false notes: >- The checkout-selected plan and quotation precede the Accounting schedule created after the deposit. - name: fulfilment and shipping summaries kind: enum required: true computed: true notes: >- Delivery and shipping progress are summaries derived from fulfilment records. - name: pricing snapshot kind: collection required: true computed: false notes: >- Stored pricing explains bound amounts, applied and rejected offers, taxes, shipping and preview timing. - name: editable notes kind: text required: false computed: false notes: >- Purchase-order reference, memo and notes remain editable; processing also updates lifecycle and financial fields. - name: history kind: collection required: true computed: false notes: >- Business events retain time, event kind, actor, correlation and structured details. relationships: - to: DOM-COM-ORD-001 cardinality: A purchase has zero or one originating cart. ownership: >- The sale retains its source reference and the completed cart identifies the sale. cross_service: false - to: DOM-COM-ORD-003 cardinality: Each purchased item routes to its type's registered seller. ownership: >- The seller retains delivery and resource meaning while Orders preserves the attested purchase. cross_service: false - to: DOM-COM-ORD-004 cardinality: A purchased line can produce one benefit of each grant kind. ownership: Entitlements retains grant ownership and its purchased-line link. cross_service: false - to: DOM-COM-ORD-005 cardinality: >- A purchase may have multiple change documents; a replacement purchase references its amendment. ownership: >- Change documents retain their targeted lines and use Orders persistence to apply later quantity effects. cross_service: false - to: DOM-ACC-TRX-001 cardinality: >- Sale, fee, installment and amendment purposes can link Accounting invoices. ownership: >- Accounting retains receivables while Commerce stores associations and financial projections. cross_service: true - to: DOM-ACC-TRX-003 cardinality: >- Successful attempts can reference their resulting Accounting money records. ownership: >- Accounting owns financial movement; Commerce retains request history and response references. cross_service: true - to: DOM-ACC-BKS-001 cardinality: A purchase is assigned to one Accounting business unit. ownership: Business-unit administration remains in Accounting. cross_service: true - to: DOM-CRM-ENT-001 cardinality: Multiple purchase party and recipient roles can reference contacts. ownership: CRM retains party records while the purchase snapshots relevant addresses. cross_service: true - to: DOM-CRM-ENT-002 cardinality: >- Purchasing, billing, shipping and recipient roles can reference organizations. ownership: Organization records remain CRM-owned. cross_service: true invariants: - id: INV-DOM-COM-ORD-002-01 statement: >- All monetary components are nonnegative, and total is subtotal minus discount plus tax, shipping and fees. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/orders.table.ts:orders_total_check, orders_amounts_check - id: INV-DOM-COM-ORD-002-02 statement: >- The same checkout cannot produce two orders, including when placement requests overlap. enforced_at: - database - service provenance: test source: >- services-commerce:modules/checkout/tests/e2e/idempotency.e2e.spec.js#answers the stored status and body, marked Idempotent-Replayed, and runs the placement once: one order row; services-commerce:modules/orders/db/orders.table.ts:orders_checkout_uq - id: INV-DOM-COM-ORD-002-03 statement: The database requires a positive order number unique within the workspace. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/orders.table.ts:orders_number_uq, orders_number_check - id: INV-DOM-COM-ORD-002-04 statement: >- The service restricts order status changes to its declared transition map and provides no exits from terminal states. enforced_at: - service provenance: observed source: >- services-commerce:modules/orders/services/persistence/orders.ts:ORDER_TRANSITIONS - id: INV-DOM-COM-ORD-002-05 statement: >- Cancelled plus returned units cannot exceed ordered units, and shipped units cannot exceed ordered units. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/orders/db/order-lines.table.ts:order_lines_quantity_check - id: INV-DOM-COM-ORD-002-06 statement: >- Database protection prevents changes to a purchase snapshot after its initial insert. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/order-line-purchases.table.ts:order_line_purchases_write_once_trigger - id: INV-DOM-COM-ORD-002-07 statement: >- An attempt has one unique Accounting key and one order sequence; resuming it retains the original payment request. enforced_at: - database - service provenance: test source: >- services-commerce:modules/orders/tests/e2e/billing-and-tender.e2e.spec.js#resumes the same attempt on a retry, whatever card the retry names, and moves nothing while the intent is processing - id: INV-DOM-COM-ORD-002-08 statement: >- An invoice link retains a unique Accounting request key and names its order and purpose. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/order-invoices.table.ts:order_invoices_idempotency_key_uq - id: INV-DOM-COM-ORD-002-09 statement: >- Order events retain their recorded actor and cannot be edited or deleted by ordinary application writes. enforced_at: - database provenance: observed source: 'services-commerce:modules/orders/db/order-events.table.ts' - id: INV-DOM-COM-ORD-002-10 statement: >- Application operations retain orders and their child records; workspace removal is the deletion boundary. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/order-lines.table.ts:order_lines_order_fk - id: INV-DOM-COM-ORD-002-11 statement: An installment schedule reference requires an installment plan selection. enforced_at: - database provenance: observed source: >- services-commerce:modules/orders/db/orders.table.ts:orders_installment_schedule_check - id: INV-DOM-COM-ORD-002-12 statement: >- Payment attempts retain account references and token suffixes without storing card data. enforced_at: - service provenance: test source: >- services-commerce:modules/orders/tests/e2e/billing-and-tender.e2e.spec.js#never stores the card: the attempt keeps a reference of the merchant account and the token’s last four only - id: INV-DOM-COM-ORD-002-13 statement: >- Reservations reference an item or line and follow the declared held and committed transitions; terminal reservations have no exits. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/orders/db/reservations.table.ts:reservations_subject_check; modules/orders/services/persistence/reservations.ts:RESERVATION_TRANSITIONS physical: - orders - order_lines - order_line_purchases - order_tenders - order_invoices - order_events - reservations evidence: - >- services-commerce at c8b66a98: modules/orders/db/orders.table.ts, order-lines.table.ts, order-line-purchases.table.ts, order-tenders.table.ts, order-invoices.table.ts, order-events.table.ts, reservations.table.ts; services/persistence/orders.ts, reservations.ts, claims.ts; services/placement/*.ts; services/billing/bill-order.ts; services/tender/tender-order.ts; services/orders/*.ts; services/mirror/*.ts; metadata/orders.object.ts; export/orders.dataset.ts, order-events.dataset.ts. - >- macroservice-libraries at 54536a44: packages/commerce-contracts (purchase, attestation, claim shapes). --- # Order ## What It Models An order is the retained record of a sale after placement. It preserves purchased items and agreed policy while tracking billing, payment attempts, resource commitments, delivery progress and later changes. Accounting remains responsible for the receivable. ## Identity and Attributes The displayed order number is distinct from its record identity. Address, policy, price and purchase snapshots preserve the agreement; processing fields and quantities can still change through their workflows. Attempts and invoice links explain financial requests, while the money mirror reports Accounting's latest known position. ## Relationships A cart can originate one sale, and an amendment can originate a change order. Selling applications own product delivery and resource claims. Grants and after-sale documents reference the purchased lines. CRM supplies party records, and Accounting owns business units, invoices and financial movements. ## Invariants The database checks monetary arithmetic, quantity bounds, uniqueness and protected purchase snapshots. Service persistence checks lifecycle changes and records the history. Stable Accounting keys support request recovery; their guarantees depend on the receiving contract as well as Commerce's own records. ## How It Is Stored and Shared Orders owns the sale and its child records. Fulfilment owns delivery obligations, settlement plans and operational exceptions in the shared database. Other applications receive participant calls rather than direct ownership of order tables. The local event trail supports export and Order 360 without publishing business events or adopting Platform record history. ## Open Design Questions Closed is declared but has no current transition caller. Recovery gaps remain around deferred provisional-invoice deletion, amendment acceptance and installment reduction. The financial integrations need live evidence beyond fixture tests.