--- id: DOM-COM-ORD-001 title: Checkout realises: CON-COM-ORD-001 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-checkout readable_by: - SVC-COM-ORD-orders - SVC-PFM-QRY-data-exports lifecycle: STATE-COM-ORD-001 custom_fields: none identity: >- A cart has a workspace-scoped, time-ordered identity rather than a display number. Placement links it to its single resulting order. attributes: - name: channel kind: enum required: true computed: false notes: 'The fixed origin of the cart: portal, console or system.' - name: purchasing subject kind: reference required: true computed: false notes: >- The caller explicitly identifies the contact or organization whose purchase rules apply; billing identity does not substitute for it. - name: acting contact and acting user kind: reference required: false computed: false notes: >- Optional attribution to the acting contact and signed-in user; system carts need not identify either. - name: bill-to party kind: reference required: true computed: false notes: >- The invoiced contact or organization, independently of the purchasing subject. - name: ship-to party kind: reference required: false computed: false notes: 'Optional shipping recipient, supplied with both party kind and identity.' - name: store kind: reference required: false computed: false notes: The selected selling store; staff carts can omit a store. - name: governing checkout policy kind: reference required: false computed: false notes: >- The selected ordering profile, its resolution source and selling context; selection can wait for the first main item. - name: currency kind: text required: false computed: true notes: Currency follows the selected policy and is absent without one. - name: items kind: collection required: false computed: false notes: >- Selections retain type, product, quantity, recipient, bundle links and buyer details, together with application advice, preparation, terms, holds and preview figures. - name: entered promotion codes kind: collection required: false computed: false notes: >- Original code entries are retained while matching uses their normalized form. - name: shipping choice kind: reference required: false computed: false notes: 'The selected shipping strategy, or no selection after clearing it.' - name: installment plan choice kind: reference required: false computed: false notes: >- A plan offered by the deposit policy, with its Accounting quotation shown in preview. - name: latest preview kind: collection required: false computed: false notes: >- Placement compares against this saved calculation, including totals, blockers and promotion results. - name: process reference kind: text required: false computed: false notes: >- An application-specific process reference limited to five hundred characters. - name: status and expiry kind: enum required: true computed: false notes: >- Lifecycle status and expiry; newly opened carts normally expire after seven days. - name: placed order kind: reference required: false computed: false notes: 'A reference to the resulting order, required only in placed status.' - name: trail kind: collection required: true computed: false notes: >- An attributed event record for mutations, assessments, reservations and placement refusals. relationships: - to: DOM-COM-ORD-002 cardinality: >- One cart can produce one sale; a sale can reference zero or one originating cart. ownership: >- The sale retains an unenforced cart reference so intended cart cleanup would not remove the permanent purchase. cross_service: false - to: DOM-COM-ORD-003 cardinality: Many item selections route to the active owner of their declared type. ownership: >- Checkout retains selection intent while the seller supplies product-specific interpretation. cross_service: false - to: DOM-CRM-ENT-001 cardinality: Several party roles may reference contacts on the same cart. ownership: >- Contact records remain CRM-owned and are referenced without copying ownership. cross_service: true - to: DOM-CRM-ENT-002 cardinality: Organization references can supply several purchasing and recipient roles. ownership: CRM retains organization ownership; checkout stores party references. cross_service: true invariants: - id: INV-DOM-COM-ORD-001-01 statement: A checkout references an order if and only if its status is placed. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/checkout/db/checkouts.table.ts:checkouts_placed_order_check - id: INV-DOM-COM-ORD-001-02 statement: 'Within a workspace, a placed-order reference belongs to only one checkout.' enforced_at: - database provenance: observed source: >- services-commerce:modules/checkout/db/checkouts.table.ts:checkouts_placed_order_uq - id: INV-DOM-COM-ORD-001-03 statement: >- Policy selection and currency are present together, with the selection source recorded. enforced_at: - database provenance: observed source: >- services-commerce:modules/checkout/db/checkouts.table.ts:checkouts_currency_check, checkouts_ordering_profile_source_check - id: INV-DOM-COM-ORD-001-04 statement: 'The service offers no transition out of placed, abandoned or cancelled.' enforced_at: - service provenance: observed source: >- services-commerce:modules/checkout/services/persistence/checkouts.ts:CHECKOUT_TRANSITIONS - id: INV-DOM-COM-ORD-001-05 statement: >- Updating an open cart increments its version and records the actor on its event trail. enforced_at: - service - database provenance: test source: >- services-commerce:modules/checkout/tests/e2e/placement.e2e.spec.js#leaves the checkout placed, naming the order, its items frozen with what prepare attested, and its trail telling the story; services-commerce:modules/checkout/services/persistence/checkouts.ts:updateCheckout, appendCheckoutEvent - id: INV-DOM-COM-ORD-001-06 statement: >- Shipping-party kind and identity must either both be supplied or both be absent. enforced_at: - database provenance: observed source: >- services-commerce:modules/checkout/db/checkouts.table.ts:checkouts_ship_to_check - id: INV-DOM-COM-ORD-001-07 statement: Workspace isolation applies to checkout reads and writes. enforced_at: - database - api provenance: test source: 'services-commerce:modules/checkout/tests/e2e/checkout-security.e2e.spec.js' - id: INV-DOM-COM-ORD-001-08 statement: >- Item quantities must be positive integers, and a bundle child must reference a parent in the cart. enforced_at: - database - service provenance: observed source: >- services-commerce:modules/checkout/db/checkout-items.table.ts:checkout_items_quantity_check; modules/checkout/services/checkout/checkout-part-checks.ts physical: - checkouts - checkout_items - checkout_events evidence: - >- services-commerce at c8b66a98: modules/checkout/db/checkouts.table.ts, checkout-items.table.ts, checkout-events.table.ts; services/persistence/checkouts.ts; services/checkout/checkout-workflow.ts, ordering-profile-resolution.ts, checkout-promotion-codes.ts, checkout-sweeper.ts; export/checkouts.dataset.ts. - >- macroservice-libraries at 54536a44: packages/commerce-contracts (party kinds, checkout channels). --- # Checkout ## What It Models A checkout holds a purchase in progress on the server. It brings together the purchasing subject, billing party, item recipients and governing policy, then saves the calculation that the buyer reviews before placement. Staff use the composer to build it; the API also supports buyers acting for their own contact. ## Identity and Attributes Order numbers are allocated only after placement. The cart keeps CRM references for its parties and application-specific purchase intents for its items. Its preview preserves the detailed calculation so placement can compare line prices and quantities, audiences, discounts and fees. ## Relationships Placement links the cart and sale without making the cart a permanent financial record. Each item's registered application supplies its meaning and preparation results. Commerce reads party information from CRM without owning those records. ## Invariants Database constraints protect the placed-order link, policy and currency pairing, complete shipping-party references and quantity bounds. Service transitions protect completed carts, while mutation persistence records versions and attributed events. The invariant rows identify the enforcement evidence. ## How It Is Stored and Shared Checkout owns the cart, item selections and event trail. Orders locks and reads the cart during placement; reservation expiry can also update its items. Application calls exchange envelopes rather than granting sellers table access. Export is available, custom fields and Quick Search are absent, and the intended thirty-day cleanup has no running sweep. ## Open Design Questions No current caller enters cancelled status. Preparing exists only within placement's transaction, and completed carts remain stored. Supporting more than one governing policy would require a product decision about splitting purchases.