Configure recommendation rules and placements

Purpose

Administrators prepare supported selling suggestions and control where they may appear.

How It Works

API clients create rules with kind-specific parameters and bind them to registered placements. The application owning a placement determines which kinds and caps it supports. Administrators activate prepared rules after binding and capacity checks. A presentation later locks substantive settings while leaving the message editable. Membership savings and application-flow actions remain delivery edges rather than fully evaluated buyer behaviour. Performance supports review of shown, accepted and converted offers. The product should approve the feature scope before designing console administration.

Relationships

The prepare and publish product presentations capability supplies related configuration or assessment used in this work.

The present offers and process buyer responses capability supplies related configuration or assessment used in this work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: Suggestions appear exclusively where a placement can show them.A rule that has been displayed does not permit edit what it offers underneath its results.
Surfaces: api

Controls

27 controls apply, from the corpus control catalogue.

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-CRY-001 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-004 TC-LOG-005 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-007 TC-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.recommendation-rules.read`	api	tenant
`commerce.recommendation-rules.create`	api	tenant
`commerce.recommendation-rules.update`	api	tenant
`commerce.recommendation-rules.activate`	api	tenant
`commerce.recommendation-rules.delete`	api	tenant
`commerce.recommendation-rules.bulk`	api	tenant
`commerce.recommendation-placements.read`	api	tenant
`commerce.recommendation-journeys.read`	api	tenant
`commerce.recommendation-journeys.create`	api	tenant
`commerce.recommendation-journeys.update`	api	tenant
`commerce.recommendation-journeys.delete`	api	tenant
`commerce.recommendation-journeys.bulk`	api	tenant

Business Rules

11 rules, 7 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Recommendation rules select related products, add-ons, upgrades or membership savings and accept only their kind’s parameters, with add-ons requiring products. proved by `ATS-COM-CAT-019-01`, `TST-COM-CAT-136`, `TST-COM-CAT-151`	validation	service	test services-commerce:modules/recommendations/tests/unit/rule-rules.spec.js#refuses an add_on rule with no products, parameters_invalid, naming the path
`02`must prove Proposed	Placement bindings must support the rule kind and constrain its offer cap to one through ten without exceeding the placement’s cap. proved by `ATS-COM-CAT-010-11`, `ATS-COM-CAT-019-02`, `ATS-COM-CAT-019-09`, `TST-COM-CAT-136`, `TST-COM-CAT-138`	validation	service, database	test services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#refuses a cap above the placement’s, 400 max_offers_exceeds_placement
`03` Proposed	Unless overridden, a rule adds its candidate to checkout or replaces the existing item for an upgrade.	policy	service	test services-commerce:modules/recommendations/tests/unit/rule-rules.spec.js#is the kind’s default: add to the checkout, or replace the item for an upgrade
`04`must prove Proposed	Application-flow actions remain unavailable, while membership-savings configuration is accepted for later evaluation. proved by `ATS-COM-CAT-019-03`, `TST-COM-CAT-136`, `TST-COM-CAT-151`	policy	service	test services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#refuses a rule whose action is start_journey, 409 action_unavailable: the journeys are R3’s
`05`must prove Proposed	Recommendation lifecycle uses draft, active, paused, ended and archived states; activation requires placement binding and a placement accepts at most twenty-five active rules. proved by `ATS-COM-CAT-019-04`, `ATS-COM-CAT-019-08`, `ATS-COM-CAT-019-10`, `TST-COM-CAT-136`, `TST-COM-CAT-148`	lifecycle	service	test services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses the twenty-sixth active rule of one placement, too_many_active_rules, naming the placement
`06`must prove Proposed	The first presentation locks rule substance while permitting message changes. proved by `ATS-COM-CAT-019-05`, `ATS-COM-CAT-019-08`, `ATS-COM-CAT-019-10`, `TST-COM-CAT-141`, `TST-COM-CAT-148`	lifecycle	service	test services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses the substance of a locked rule, rule_locked, naming the columns, while the message stays editable
`07`must prove Proposed	Recommendation names are workspace-unique and deterministic subject assignment can withhold offers from up to half the audience. proved by `ATS-COM-CAT-019-06`, `TST-COM-CAT-148`, `TST-COM-CAT-150`	validation	service, database	test services-commerce:modules/recommendations/tests/unit/holdout.spec.js#answers the same bucket for the same subject and rule every time
`08` Proposed	Five store placements cover catalog, product, cart, checkout review and order confirmation, while applications register placements and flows under their own names.	policy	service	test services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-placements.integration.spec.js#inserts the five store placements the first time, under commerce, declared now
`09` Proposed	Application-flow registrations are unique per kind and refuse updates or deletion while locked.	lifecycle	service	test services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-journeys.integration.spec.js#refuses to update or delete a locked journey, record_locked
`10` Proposed	Recommendation performance aggregates shown, accepted and converted offers and their value by placement and day.	calculation	service	test services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-performances.queries.integration.spec.js#answers one row per placement and day, counted from the rows: the cart on the seventh and the review on the eighth
`11`must prove Proposed	Rules and placements require their read permissions; rule and flow writes require administrator permissions and launch or resume requires separate activation authority. proved by `ATS-COM-CAT-019-07`, `TST-COM-CAT-137`	permission	api	test services-commerce:modules/recommendations/tests/e2e/recommendations-security.e2e.spec.js#lists the rules and the placements, and is refused a create and an activation 403 permission_missing

Scenarios

Id	Given	When	Then	Provenance
`01`	A related-products rule is bound to the cart	Exercise the supported lifecycle sequence	It passes through active, paused, active, ended and archived, refusing unsupported transitions	test services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#moves through active, paused, active, ended, archived

Planning

Implementation

Configure recommendation rules and placements ​

Purpose ​

How It Works ​

Relationships ​