--- id: SVC-COM-CAT-recommendations title: 'Recommendations: offer rules, placements, flows, presentations and responses' product_area: commerce module: catalog repository: services-commerce source_module: modules/recommendations revision: 1 status: draft design_intent: open implementation_evidence: observed inference: [] source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-COM-CAT-006 does_not_own: - MOD-COM-ORD controls checkout item changes. - SVC-COM-CAT-pricing calculates the offered price. - SVC-COM-CAT-promotions applies campaign codes. - MOD-PFM-ELG owns audience eligibility; this service stores bindings without evaluating them. operations: - operation_id: createRecommendationRule intent: Prepare a new suggestion rule with validated configuration. access: console permission: commerce.recommendation-rules.create realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listRecommendationRules intent: Browse the workspace’s suggestion rules using supported filters. access: console permission: commerce.recommendation-rules.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getRecommendationRule intent: Inspect the selected suggestion rule and its retained details. access: console permission: commerce.recommendation-rules.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateRecommendationRule intent: Save permitted changes to the selected suggestion rule at its read version. access: console permission: commerce.recommendation-rules.update realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: activateRecommendationRule intent: Launch the suggestion rule after required activation checks. access: console permission: commerce.recommendation-rules.activate realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: pauseRecommendationRule intent: Suspend participation by the suggestion rule while retaining its records. access: console permission: commerce.recommendation-rules.update realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: resumeRecommendationRule intent: Restore participation by the paused suggestion rule after activation checks. access: console permission: commerce.recommendation-rules.activate realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: endRecommendationRule intent: Stop the suggestion rule permanently while keeping its history. access: console permission: commerce.recommendation-rules.update realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: archiveRecommendationRule intent: Retain the eligible suggestion rule as archived and exclude it from ordinary use. access: console permission: commerce.recommendation-rules.update realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getRecommendationRulePerformance intent: 'Inspect rule presentation, response and conversion measures by placement and day.' access: console permission: commerce.recommendation-rules.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listRecommendationPlacements intent: Browse the workspace’s offer placements using supported filters. access: console permission: commerce.recommendation-placements.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getRecommendationPlacement intent: Inspect the selected offer placement and its retained details. access: console permission: commerce.recommendation-placements.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: createRecommendationJourney intent: Prepare a new application flow declaration with validated configuration. access: console permission: commerce.recommendation-journeys.create realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: listRecommendationJourneys intent: Browse the workspace’s application flow declarations using supported filters. access: console permission: commerce.recommendation-journeys.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: getRecommendationJourney intent: Inspect the selected application flow declaration and its retained details. access: console permission: commerce.recommendation-journeys.read realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: updateRecommendationJourney intent: Save permitted changes to the selected application flow declaration at its read version. access: console permission: commerce.recommendation-journeys.update realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: deleteRecommendationJourney intent: Remove the selected application flow declaration when protection and dependencies permit. access: console permission: commerce.recommendation-journeys.delete realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: evaluateOffers intent: 'Assess and record suggestions for an authorized subject, or run a staff-only unsaved preview.' access: portal permission: commerce.offers.read realises: - CAP-COM-CAT-020 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: evaluatePublicOffers intent: Assess public-price suggestion estimates for an anonymous session. access: public permission: none (anonymous) realises: - CAP-COM-CAT-020 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: acceptOffer intent: Perform the shown offer’s supported action and record its outcome. access: portal permission: commerce.offers.respond realises: - CAP-COM-CAT-020 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: dismissOffer intent: Record a shown offer’s dismissal without duplicating dismissal history. access: portal permission: commerce.offers.respond realises: - CAP-COM-CAT-020 published_to_submissions: 'not published: this operation has no registered Submissions binding' - operation_id: recommendations.seedStorePlacements intent: Insert absent Commerce storefront placements during workspace setup. access: internal permission: none (provisioning) realises: - CAP-COM-CAT-019 published_to_submissions: 'not published: this operation has no registered Submissions binding' events: [] jobs: [] integrations: - system: Participant manifests direction: inbound contract: Participant manifests can declare placements and flow kinds; workspace materialization remains deferred. - system: Workspace data export direction: outbound contract: Offer telemetry export includes presentations and interactions. consistency: - rule: Presentation insertion and first-presentation protection commit together. kind: transactional compensation: A failed transaction commits neither. - rule: >- Item action and acceptance history share a transaction, but history uniqueness alone does not serialize concurrent first actions. kind: transactional compensation: Refused item processing rolls back its transaction; once-only concurrent effects need proof. - rule: Promotion-code application commits separately from acceptance history. kind: eventual compensation: No automatic rollback removes a code applied before a failed history write. evidence: - >- services-commerce at c8b66a98: modules/recommendations/aws/api/*.routes.ts, services/**/*.ts, db/*.table.ts, export/offer-telemetry.dataset.ts. 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-005, 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-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-AVL-002, TC-AVL-003, TC-AVL-004, TC-AVL-005, TC-MON-001, TC-MON-003, TC-MON-004, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PRV-001, TC-PRV-002] --- # Recommendations: offer rules, placements, flows, presentations and responses ## What This Service Is For Recommendations deterministically selects and prices suggestions at registered placements and records presentation and response outcomes. This remains implemented scope awaiting product approval. ## Boundary Rules, placements, flow declarations and telemetry belong here. Checkout workflows execute item actions, pricing quotes supply amounts and promotion seams apply codes. Saved audience bindings are not yet evaluated. ## Operations in Words Staff APIs maintain rules and flow declarations and review placement or performance information. Members can assess and respond to offers; anonymous sessions receive unacceptable estimates at public placements. Staff preview leaves no presentation record. No staff configuration screen exists for this scope. ## Events and Jobs Recommendations has no background processing or external event publication. Presentation retention remains deferred. Its empty inference list reflects deterministic rules and message formatting, with no model call. ## Consistency Guarantees Presentation and rule protection writes are atomic. Item actions share a transaction with their history, but the history index does not prove once-only concurrent actions. Code application commits before separate acceptance recording.