--- id: WF-MBR-MEM-011 title: Prepare a checkout's membership items trigger: Commerce asks for advice or preparation of membership items in a checkout. product_area: membership module: memberships revision: 1 status: draft design_intent: proposed implementation_evidence: observed inference: [] source_sha: services-membership: 5994c270e8a37a30f848e99ba5b5ee6b87c08893 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f implements: - CAP-MBR-MEM-009 - CAP-MBR-MEM-011 moves: [] crosses: - SVC-MBR-MEM-commerce-participant - SVC-MBR-MEM-applications idempotency: >- Preparation has no writes. Repeating against unchanged business date and records produces the same normalized payload; intervening changes can alter the answer. concurrency: >- Preparation does not hold write locks. Placement performs the authoritative reservation checks within Commerce’s transaction. hops: - 'n': 1 actor_or_service: Commerce action: >- Validate the participant envelope and contract version at the function boundary. anchor: >- services-membership:modules/commerce-participant/services/participant-handler.ts:handleParticipantRequest seam: sync on_failure: >- Reject invalid envelope or version without retry; propagate unexpected errors for Commerce retry. left_inconsistent: No partial local change remains. observer: Commerce checkout result provenance: observed source: >- services-membership:modules/commerce-participant/services/participant-handler.ts (header) - 'n': 2 actor_or_service: Commerce participant action: >- Validate each package product against its program, type and package configuration. anchor: >- services-membership:modules/commerce-participant/services/prepare/prepare-purchase.ts:preparePackageItem seam: sync on_failure: Return a coded package-validation refusal without writes. left_inconsistent: No partial local change remains. observer: Buyer-visible checkout refusal provenance: test source: >- services-membership:modules/commerce-participant/tests/integration/participant.integration.spec.ts#refuses a package line whose product is not the package - 'n': 3 actor_or_service: Commerce participant action: >- Determine which operation the current member state permits and reject an incompatible requested operation. anchor: >- services-membership:modules/commerce-participant/services/prepare/eligibility.ts:decideEligibility seam: sync on_failure: >- Return the supported operation or unavailability reason without substituting a different purchase. left_inconsistent: No partial local change remains. observer: Buyer-visible checkout answer provenance: test source: >- services-membership:modules/commerce-participant/tests/unit/eligibility.spec.ts#refuses a renewal of a lapsed membership, naming rejoin - 'n': 4 actor_or_service: Commerce participant action: >- Calculate coverage, units, dues components, grants, exclusivity, pricing audience and selling context. anchor: >- services-membership:modules/commerce-participant/services/prepare/purchase-plan.ts:purchasePlanOf seam: sync on_failure: 'Reject an incomplete component plan, including a missing dues line.' left_inconsistent: No partial local change remains. observer: Buyer-visible checkout answer provenance: test source: >- services-membership:modules/commerce-participant/tests/integration/participant.integration.spec.ts#refuses a package line whose dues chapter has no dues line be - 'n': 5 actor_or_service: Applications service action: >- Check active reviewing processes and any supplied approved application to determine the approval answer. anchor: >- services-membership:modules/commerce-participant/services/prepare/prepare-purchase.ts:approvalOf seam: sync on_failure: >- Return the complete plan with approval-required status; no reservation is made. left_inconsistent: No partial local change remains. observer: Commerce approval-required answer provenance: test source: >- services-membership:modules/applications/tests/integration/decision-handler.integration.spec.ts#answers requires_approval for the package the process reviews - 'n': 6 actor_or_service: Commerce participant action: >- Return normalized payload, attestation, fulfilment plan, price context and reservation claim without monetary amounts. anchor: >- services-membership:modules/commerce-participant/services/prepare/prepare-purchase.ts:preparePurchase seam: sync on_failure: This step has no separate failure outcome. left_inconsistent: No partial local change remains. observer: Commerce preparation result provenance: test source: >- services-membership:modules/commerce-participant/tests/unit/purchase-plan.spec.ts#carries no amount anywhere branches: - >- A different type bought at the existing term end uses renewal; an immediate amendment remains refused. - >- Officer, application and billing callers share checkout preparation before asking Commerce to place orders. waits: [] evidence: - >- services-membership at 5994c270: modules/commerce-participant/services/prepare/*.ts; services/participant-handler.ts; contracts/* controls: [TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-007, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, 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, TC-SEC-001, TC-SEC-004, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004] --- # Prepare a checkout's membership items ## What It Does Checkout preparation explains the coverage a purchase would provide without reserving it. Membership supplies eligibility, dates, units, grant plans and pricing context for Commerce. ## The Flow ```mermaid flowchart TD H1["Validate the participant envelope and contract version at the function boundary"] H2["Validate each package product against its program, type and package configuration"] H1 --> H2 H3["Determine which operation the current member state permits and reject an incompatible requested operation"] H2 --> H3 H4["Calculate coverage, units, dues components, grants, exclusivity, pricing audience and selling context"] H3 --> H4 H5["Check active reviewing processes and any supplied approved application to determine the approval answer"] H4 --> H5 H6["Return normalized payload, attestation, fulfilment plan, price context and reservation claim without monetary amounts"] H5 --> H6 ``` ## When Something Fails A malformed envelope is a non-retryable contract failure; unexpected errors propagate for caller retry. Eligibility and configuration refusals produce coded item results. Approval-required is a supported answer and reserves nothing.