--- id: CON-COM-CAT-006 name: Recommendation feature: FEAT-COM-CAT-05 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: partially-observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b definition: >- A recommendation combines a configured suggestion rule with the buyer-specific offer presentations and responses it produces at an application placement. owned_by: MOD-COM-CAT synonyms: - Offer (what a buyer sees) - Upsell or cross-sell not_to_be_confused_with: - The campaign benefit assessed during pricing - The catalog association supplying suggestion candidates facets: - name: Rule kind meaning: >- Kind-specific parameters describe related items, add-ons, upgrades or deferred membership savings. used_for: Selecting the recommendation category. - name: Placement meaning: Application-declared spots limit supported kinds and offer counts. used_for: Declaring the presentation context. - name: Action and flow meaning: >- Acceptance can add or replace an item or use another supported response action; application-flow execution remains deferred. used_for: Connecting response with a supported action. - name: Holdout and suppression meaning: >- Stable holdouts and suppression choices distinguish deliberate withholding from ordinary candidate exclusion. used_for: Separating withheld subjects and suppressed repetitions. - name: Presentation and interaction meaning: >- Shown and withheld presentations and accepted or dismissed interactions preserve the basis for performance. used_for: Retaining measurement and idempotent response records. relationships: - to: CON-COM-CAT-004 statement: Each offer is priced for the purchaser by the pricing calculation. provenance: test source: >- services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#answers one offer: the mug, from the listing, priced $12.00 by the quote, live, to add to the checkout, expiring with the quote - to: CON-COM-CAT-003 statement: A listing’s associations provide related-product candidates. provenance: observed source: >- services-commerce:modules/recommendations/services/evaluation/evaluate-offers.ts:1 lifecycle: - state: Draft meaning: Being prepared; presents nothing. how_it_changes: Activation follows a valid placement binding. - state: Active meaning: Active evaluation can generate placement presentations. how_it_changes: Pause or end actions change its availability. - state: Paused meaning: Paused rules produce no live offers. how_it_changes: Resume restores operation and end stops it. - state: Ended and archived meaning: Ending prevents further operation before archive. how_it_changes: Final. acted_on_by: - CAP-COM-CAT-019 - CAP-COM-CAT-020 visible_to: - ACT-COM-001 - ACT-COM-004 - ACT-COM-005 - ACT-COM-006 evidence: - >- Pinned service inputs: modules/recommendations (rules, placements, journeys, evaluation, acceptance, holdout, messages), the milestones index (COMM-M7, Proposed) supersedes: [] --- # Recommendation ## What It Is A recommendation connects a selling suggestion with the situation in which a buyer might find it useful. Staff can configure related products, an add-on or an upgrade for a particular placement such as a product page or cart. The rule describes the suggestion; an offer is the priced presentation produced for a subject at a moment in that placement. The distinction matters when staff evaluate performance. One rule can produce many presentations for different subjects, and each presentation can receive a response. A related mug beside a shirt is therefore an instance of configured selling guidance, with its own candidate, calculated price, action and expiry. It is not simply another product displayed without context. Applications declare placements and the kinds of offers those placements support. Store placements already exist, while other applications can register their own. The module can retain configuration ahead of full evaluation support, so stored membership-savings parameters do not establish that buyers currently receive those offers. No console administration screen or accepted recommendation milestone confirms the whole feature today. ## What It Is Not A recommendation is separate from the promotion that changes price and from the order that records a purchase. An offer may lead to a checkout change, a page or a code action, but it does not become an order merely because it is shown. Expiry limits a new response; it does not demonstrate that the displayed amount is preserved through acceptance and placement. ## How It Is Used Administrators configure supported rules through the API and bind them to placements before activation. Evaluation quotes candidates for the subject and suppresses unsuitable repetitions. Buyers can accept or dismiss shown offers, while anonymous visitors receive estimates requiring a new signed-in presentation before acceptance. Staff previews explain suppression without recording live presentations. A response can fail because the offer is expired, belongs to another subject or requires an unavailable action. ## Its Facets **Suggestion kind.** Kind-specific parameters describe related items, add-ons, upgrades or deferred membership savings. **Placement.** Application-declared spots limit supported kinds and offer counts. **Action.** Acceptance can add or replace an item or use another supported response action; application-flow execution remains deferred. **Measurement and restraint.** Stable holdouts and suppression choices distinguish deliberate withholding from ordinary candidate exclusion. **Presentation and response.** Shown and withheld presentations and accepted or dismissed interactions preserve the basis for performance. ## How It Relates Catalog related-product selections supply some candidates, pricing supplies their amounts and checkout performs item actions. Orders retain accepted offer references for conversion reporting. Applications own their placement names and any registered flows rather than transferring their domain work into recommendations. ## What It Could Become The product should approve the recommendation scope before designing staff and buyer screens. It should settle the price promise, prove changed-price and expired-repeat behaviour, and join promotion-action acceptance records to checkout changes so a failure cannot leave an unexplained partial response.