--- id: SVC-COM-ORD-checkout title: Checkout Service Module product_area: commerce module: orders repository: services-commerce source_module: modules/checkout 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-001 does_not_own: - 'Orders retains sale, purchased-line and reservation ownership despite checkout hosting placement.' - 'Catalog retains policy, store, purchasing configuration, pricing, offers and interim tax ownership.' - 'Fulfilment retains shipping configuration, rating and delivery obligations.' - CRM retains parties and addresses; Platform retains eligibility evaluation. operations: - operation_id: getCheckoutHealth intent: Expose checkout runtime health and build information without customer data. access: public permission: 'none: public health route' realises: [] published_to_submissions: 'not published: runtime status is outside submission processing.' - operation_id: createCheckout intent: Create a purchasing cart and resolve its first selections and governing policy. access: portal permission: >- commerce.checkouts.create (the workflow also evaluates commerce.orders.create for the organization override) realises: - CAP-COM-ORD-001 - CAP-COM-ORD-002 - CAP-COM-ORD-011 published_to_submissions: >- not published: creating a buyer cart has no submission-stage contract; the need for one remains undecided. - operation_id: getCheckout intent: 'Retrieve selections, the saved calculation and promotion results for a cart.' access: portal permission: commerce.checkouts.read realises: - CAP-COM-ORD-001 - CAP-COM-ORD-011 published_to_submissions: 'not published: cart retrieval is not a submission-stage operation.' - operation_id: addCheckoutItem intent: Insert another selection and resolve policy if the first main item determines it. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-001 - CAP-COM-ORD-002 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: changeCheckoutItem intent: 'Replace the selected quantity, recipient or product-specific details.' access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-001 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: removeCheckoutItem intent: Delete a selection and return any associated application hold. access: portal permission: commerce.checkouts.update realises: - CAP-COM-ORD-001 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: previewCheckout intent: 'Calculate and save prices and blockers, including offers and any selected payment plan.' access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-003 - CAP-COM-ORD-004 - CAP-COM-ORD-009 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: applyCheckoutPromotionCode intent: Record an entered offer code and return an updated assessment. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-004 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: removeCheckoutPromotionCode intent: Remove a normalized matching offer code and recalculate the cart. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-004 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: abandonCheckout intent: End shopping on an open cart and return its holds. access: portal permission: commerce.checkouts.update realises: - CAP-COM-ORD-001 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: requestCheckoutItemHold intent: Request a reservation before placement from the selection's seller. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-001 - CAP-COM-ORD-012 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: extendCheckoutItemHold intent: Request more reservation time within the seller's permitted limit. access: portal permission: commerce.checkouts.update realises: - CAP-COM-ORD-001 - CAP-COM-ORD-012 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: changeCheckoutOrderingProfile intent: Allow staff to replace the open cart's active policy and validate its new currency context. access: console permission: commerce.checkouts.update realises: - CAP-COM-ORD-002 published_to_submissions: 'not published: staff policy correction is outside submission intake.' - operation_id: chooseCheckoutShipping intent: Select or clear a shipping option and return its updated price. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-001 - CAP-COM-ORD-003 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: chooseCheckoutInstallmentPlan intent: Select or clear an offered deposit plan and return Accounting's quotation. access: portal permission: commerce.checkouts.update (evaluates commerce.orders.create) realises: - CAP-COM-ORD-009 published_to_submissions: 'not published: no submission stage invokes this cart mutation.' - operation_id: listCatalogProductTypes intent: 'Retrieve currently sellable types, their owners and available payload-schema versions.' access: portal permission: commerce.checkouts.read realises: - CAP-COM-ORD-012 published_to_submissions: 'not published: selling discovery has no submitting workflow contract.' - operation_id: placeCheckout intent: >- Recalculate and commit an open cart as one sale, comparing any saved preview and preserving replay under a required request key. access: portal permission: commerce.orders.create realises: - CAP-COM-ORD-005 - CAP-COM-ORD-006 - CAP-COM-ORD-011 published_to_submissions: 'not published: placement recalculates the buyer cart; a submission purchase contract remains undecided.' events: - name: >- checkout trail events (created, item added and changed, previewed, hold acquired, released and expired, placement refused, prepared, transitioned) direction: produced when: 'Cart editing, assessment, resource holds and refused actions append trail entries.' payload_summary: >- The local trail retains cart identity, attributed actor, correlation and action details without an external event publication. jobs: - name: commerce_checkout_sweeper schedule: 'every minute, reserved concurrency one' purpose: >- The checkout function runs cart expiry followed by resource, tender, registration, financial and grant recovery, plus daily request-key cleanup. integrations: - system: Selling applications direction: outbound contract: >- Version-one seller declarations support advice, preparation, hold extension and resource release through the shared Commerce contracts. - system: Platform eligibility direction: outbound contract: Eligibility functions decide purchase and promotion qualification. - system: Accounting direction: outbound contract: Accounting functions calculate installment and tax quotes. - system: CRM direction: outbound contract: 'CRM tables supply parties, relationships and addresses without Commerce ownership.' - system: Platform users direction: outbound contract: User records supply the contact associated with a portal identity. consistency: - rule: Cart edits persist their attributed trail and version within the same commit. kind: transactional compensation: Rollback preserves the previous cart and trail. - rule: Assessment captures a moment in time; placement independently verifies relevant figures. kind: eventual compensation: A changed calculation requires renewed buyer review. - rule: Resource release participates in the cart transaction through the seller database function. kind: transactional compensation: Failed release rolls back its cart change. - rule: 'A healthy bounded sweep eventually abandons expired carts, subject to backlog.' kind: eventual compensation: Later invocations revisit remaining eligible carts. evidence: - >- services-commerce at c8b66a98: modules/checkout/aws/api/checkout.routes.ts, checkouts.routes.ts (route declarations), checkouts.schemas.ts, checkout-api-mapper.ts; aws/checkout.module.ts; aws/lambda/API.handler.ts, SWEEPER.ts; services/**; db/*.table.ts; aws/commerce.service.ts (CheckoutsPermissions, OrdersPermissions). controls: [TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, 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-DAT-004, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-AVL-005, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] --- # Checkout Service Module ## What This Service Is For Checkout holds purchases in progress and exposes their selection, assessment and placement operations. The composer uses those operations for staff purchases; portal calls are restricted to the buyer's authority. This module also hosts the shared background schedule. ## Boundary The module owns carts, selections and their trail. Catalog supplies policies, stores, prices and offers; CRM supplies purchasing parties; Platform supplies eligibility. Placement is hosted here but writes through the owners of sale, resource, redemption and delivery records in one shared transaction. ## Operations in Words Cart operations create, edit, reserve, assess and abandon selections. Staff can switch policy; callers can choose shipping and offered deposit plans. Code changes recalculate the preview, while placement requires its own permission and request key. No operation declares a Submissions publication. ## Events and Jobs Cart events are local history rather than externally published messages. The minute schedule runs expiry, reservation, payment-window, register, financial and grant work in order, followed by ledger purge during its daily window. ## Consistency Guarantees Mutation and history writes share a commit, including releases through application database functions. Preview is a saved assessment rather than a lasting price guarantee. Scheduled expiry depends on the pass reaching the record without a propagated earlier failure.