--- id: WF-COM-ORD-001 title: Build a cart and preview its price trigger: 'Cart creation, an item edit or an explicit assessment request starts purchase preparation.' product_area: commerce module: orders revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-COM-ORD-001 - CAP-COM-ORD-002 - CAP-COM-ORD-003 - CAP-COM-ORD-004 - CAP-COM-ORD-009 - CAP-COM-ORD-011 moves: - STATE-COM-ORD-001 - STATE-COM-ORD-002 - STATE-COM-ORD-003 crosses: - SVC-COM-ORD-checkout - SVC-COM-ORD-participants - SVC-COM-ORD-orders - SVC-CRM-ENT-entities - SVC-PFM-ELG-eligibility - SVC-ACC-TRX-transactions idempotency: >- Optional request keys replay completed cart writes. Unkeyed item addition can add another item, while repeated code entry is refused. Preview recomputes and replaces the saved assessment. concurrency: >- Cart mutations lock the cart and increment its version. Assessment writes compare the version read, and the composer queues its requests so one screen does not race its own edits. hops: - 'n': 1 actor_or_service: Checkout route action: >- Establish caller authority and validate selections, then resolve policy from explicit choice, store, first main-item context, application default or workspace default. anchor: 'services-commerce:modules/checkout/services/checkout/checkout-workflow.ts:openCheckout' seam: sync on_failure: Validation returns specific problems before creating the cart. left_inconsistent: No partial cart is retained. observer: 'Observed through the requesting buyer or staff member, from the refusal.' provenance: test source: 'services-commerce:modules/checkout/tests/e2e/ordering-profile-resolution.e2e.spec.js' - 'n': 2 actor_or_service: Checkout route action: >- Mutate the selected items after checking organization roles and affiliation or recording a staff override, with a matching event. anchor: 'services-commerce:modules/checkout/services/checkout/checkout-workflow.ts:addItem' seam: sync on_failure: Any validation problems stop the mutation. left_inconsistent: The previous cart remains intact. observer: Observed through the requesting buyer or staff member; the cart action trail for overrides. provenance: observed source: 'services-commerce:modules/checkout/services/checkout/purchasing-roles.ts' - 'n': 3 actor_or_service: Selling application action: 'Request or extend an early resource hold within the seller''s policy, and release it on removal.' anchor: 'services-commerce:modules/checkout/services/checkout/checkout-workflow.ts:requestHold' seam: sync on_failure: >- Seller refusal, unsupported holds or unavailability stop the request; a lost response does not prove the seller wrote nothing. left_inconsistent: A remotely created hold can be absent from Commerce until the seller expires it. observer: Observed through the requesting buyer or staff member; the hold sweep for lapsed holds. provenance: test source: >- services-commerce:modules/checkout/tests/e2e/holds-and-claims.e2e.spec.js#refuses another buyer the booth: 409 hold_unavailable with the participant’s reason, and their preview marks the item unavailable - 'n': 4 actor_or_service: Store extension action: Run the store's preprocessing extension before assessment. anchor: 'services-commerce:modules/checkout/services/checkout/checkout-preprocessing.ts:preprocessCheckout' seam: sync on_failure: Failure of a required extension stops assessment; optional extension failure is recorded and skipped. left_inconsistent: No priced preview is committed by the failed assessment. observer: Observed through the requesting buyer or staff member; the cart action trail. provenance: test source: 'services-commerce:modules/checkout/tests/e2e/checkout-preprocessing.e2e.spec.js' - 'n': 5 actor_or_service: Selling applications action: 'Obtain item advice, plans and price adjustments under the five-second participant timeout.' anchor: 'services-commerce:modules/checkout/services/checkout/participant-calls.ts' seam: sync on_failure: Missing answers return retryable unavailability without closing the cart. left_inconsistent: The new assessment snapshot is not saved. observer: Observed through the requesting buyer or staff member. provenance: test source: 'services-commerce:modules/checkout/tests/e2e/participant-unavailable.e2e.spec.js' - 'n': 6 actor_or_service: 'Pricing, promotions and eligibility' action: >- Calculate audience prices, provisional same-cart benefits, purchase eligibility, automatic and entered offers, and the order fee. anchor: 'services-commerce:modules/checkout/services/checkout/checkout-assessment.ts:assessCheckout' seam: sync on_failure: >- Missing or prohibited prices, denied or indeterminate eligibility and rejected codes are returned as preview problems. left_inconsistent: No final sale or promotion use is recorded. observer: 'Observed through the requesting buyer or staff member, from the preview''s problems.' provenance: test source: 'services-commerce:modules/checkout/tests/e2e/product-purchase-eligibility.e2e.spec.js' - 'n': 7 actor_or_service: Shipping and tax action: >- Calculate the selected shipping option, tax discounted lines at the resolved address and quote any selected installment plan. anchor: 'services-commerce:modules/checkout/services/checkout/checkout-taxation.ts:taxPricedItems' seam: sync on_failure: Address failures block the purchase; an unanswered Accounting quotation returns unavailability. left_inconsistent: The cart remains a purchase in progress. observer: Observed through the requesting buyer or staff member. provenance: test source: 'services-commerce:modules/checkout/tests/e2e/accounting-tax.e2e.spec.js' - 'n': 8 actor_or_service: Checkout persistence action: 'Persist item assessment, calculated amounts and the preview event without redeeming offers.' anchor: 'services-commerce:modules/checkout/services/persistence/checkouts.ts' seam: sync on_failure: An outdated cart version requires another preview. left_inconsistent: A conflicting preview cannot replace the newer cart. observer: Observed through the requesting buyer or staff member. provenance: test source: 'services-commerce:modules/checkout/tests/e2e/checkouts.e2e.spec.js' - 'n': 9 actor_or_service: Checkout sweeper action: 'Expire stale item holds and abandon overdue open carts, releasing their reservations.' anchor: 'services-commerce:modules/checkout/services/checkout/checkout-sweeper.ts:sweepExpiredCheckouts' seam: schedule on_failure: Changed carts are skipped; unexpected failures terminate the invocation and its remaining passes. left_inconsistent: Overdue carts remain open until later processing succeeds. observer: Observed through function logging and failure alerting. provenance: observed source: 'services-commerce:modules/checkout/aws/lambda/SWEEPER.ts:handler' branches: - The first main item resolves policy when the cart has none. - 'Staff can select another active policy while the cart is open, subject to seller context restrictions.' - Changing the purchasing party in the composer starts a replacement cart. waits: - An open cart remains available until placement or expiry. evidence: - >- services-commerce at c8b66a98: modules/checkout/aws/api/checkouts.routes.ts; services/checkout/*.ts; services/persistence/checkouts.ts; tests/e2e/*.e2e.spec.js. - 'react-console at baf6dae3: lib/commerce/composer/live.ts (serialised requests, abandon on party change).' controls: [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] --- # Build a cart and preview its price ## What It Does Cart preparation resolves the sale policy, checks each selection and optionally reserves scarce resources. The saved preview explains prices and blockers and becomes the comparison point for placement. ## The Flow ```mermaid sequenceDiagram participant C as Clerk or buyer participant K as Checkout participant A as Selling application participant P as Pricing, promotions, eligibility participant X as Accounting C->>K: open cart, add items K->>A: advise (selling context) K-->>C: cart with its policy C->>K: hold item (optional) K->>A: prepare with hold C->>K: preview K->>A: advise each item K->>P: price, rules, promotions K->>X: installment quote (when chosen) K->>K: save snapshot and preview event K-->>C: preview with problems ``` ## When Something Fails Validation failures preserve the previous cart. Required extension or seller unavailability stops assessment; optional extensions can be skipped with an event. Blocking business outcomes appear in a successful preview. A hold created remotely before a lost response can remain until its own expiry. ## Open Design Questions Preview performs writes, and completed-cart cleanup has no scheduled caller. The wider cart process reference is withheld when it cannot fit the shared envelope.