Present offers and process buyer responses

Purpose

Commerce produces contextual suggestions and records permitted acceptances or dismissals.

How It Works

Evaluation uses the placement, subject and selling context to build candidate offers. Pricing supplies candidate amounts and suppression keeps unnecessary repetitions out of the response. Live evaluation retains presentations, while staff preview returns diagnostics without that write. A buyer can respond to a permitted presentation through its action. Checkout item actions and acceptance records are joined for add and replacement paths. Expiry prevents a new late acceptance, but does not freeze the displayed amount or invalidate an earlier recorded result. The product should prove those distinctions and resolve the separate promotion-action transaction gap.

Relationships

The configure recommendation rules and placements capability supplies related configuration or assessment used in this work.

The calculate and explain a buyer’s item price 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: Suppression respects existing purchases and recent dismissals.A suggestion taken is added once, at the price displayed.
Surfaces: portalapi

Controls

26 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-TEN-004 TC-CRY-001 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-LOG-004 TC-LOG-005 TC-AVL-004 TC-AVL-005 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.offers.read`	api	tenant
`commerce.offers.respond`	api	tenant

Business Rules

11 rules, 9 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	Evaluation ranks active rules for a placement and subject, quotes each candidate for that subject and applies request, rule and placement limits. proved by `ATS-COM-CAT-019-08`, `ATS-COM-CAT-020-01`, `TST-COM-CAT-135`	calculation	service	test 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
`02`must prove Proposed	Configured suppression removes candidates already in checkout, previously accepted or recently dismissed, using thirty days as the default dismissal interval. proved by `ATS-COM-CAT-020-02`, `ATS-COM-CAT-020-08`, `TST-COM-CAT-135`	policy	service	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#offers nothing inside the dismissal window
`03`must prove Proposed	First acceptance checks the fifteen-minute expiry, while recorded acceptances remain repeatable after expiry and added items do not retain a frozen offer price. proved by `ATS-COM-CAT-020-03`, `ATS-COM-CAT-020-08`, `TST-COM-CAT-135`	lifecycle	service	observed services-commerce:modules/recommendations/services/acceptance/accept-offer.ts:acceptOffer
`04`must prove Proposed	Accepting an add or upgrade offer changes the buyer’s checkout once and records the offer reference, with repeats returning the saved result. proved by `ATS-COM-CAT-020-01`, `ATS-COM-CAT-020-08`, `TST-COM-CAT-135`	policy	service, database	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#answers the first acceptance to a second, repeated, adding nothing
`05`must prove Proposed	Portal response authority follows the presented contact, acting contact or accessible checkout; console staff may respond within the workspace, and repeated dismissal records no additional interaction. proved by `ATS-COM-CAT-020-02`, `ATS-COM-CAT-020-08`, `TST-COM-CAT-135`	permission	service	observed services-commerce:modules/recommendations/services/acceptance/accept-offer.ts:ownedOffer
`06`must prove Proposed	Anonymous subjects receive public-price estimates only in public placements, and those estimate presentations cannot be accepted. proved by `ATS-COM-CAT-020-04`, `TST-COM-CAT-135`	policy	service	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#cannot have the estimate accepted, even by a signed-in member: 409 sign_in_required
`07` Proposed	Holdout assignment is recorded without presenting that rule’s offer to the withheld subject.	policy	service	test services-commerce:modules/recommendations/tests/unit/holdout.spec.js#holds a subject out exactly when its bucket is below ten times the percentage
`08`must prove Proposed	Staff-only offer preview reports suppression reasons and persists no presentation. proved by `ATS-COM-CAT-020-05`, `TST-COM-CAT-135`	permission	service	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#is refused to a portal member, 403 preview_not_allowed, and answers the console the suppressed rules without writing
`09` Proposed	An accepted offer reference passes from the checkout item to its order line for conversion measurement.	invariant	service	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#places the order with the offer frozen on the mug’s line
`10`must prove Proposed	Offer evaluation requires read permission, response requires respond permission, and anonymous evaluation requires neither but rejects person or cart references. proved by `ATS-COM-CAT-020-06`, `TST-COM-CAT-137`	permission	api	test services-commerce:modules/recommendations/tests/e2e/recommendations-security.e2e.spec.js#may evaluate but not accept: 403 permission_missing on the acceptance
`11`must prove Proposed	Live offer evaluation persists shown and held-out presentations and locks their producing rules in the same transaction, while preview evaluation omits those writes. proved by `ATS-COM-CAT-020-07`, `ATS-COM-CAT-020-08`, `ATS-COM-CAT-020-09`, `ATS-COM-CAT-020-10`	lifecycle	service	observed services-commerce:modules/recommendations/services/persistence/offer-presentations.ts:insertOfferPresentations

Scenarios

Id	Given	When	Then	Provenance
`01`	A member’s t-shirt cart produces a related mug offer	Accept the mug and complete the order	The offer reference follows the item and performance records a twelve-dollar converted line	test services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#shows one shown, one accepted and one converted line worth $12.00 on the rule’s performance once the order is accepted

Planning

Implementation

Present offers and process buyer responses ​

Purpose ​

How It Works ​

Relationships ​