Retain and review promotion usage

Purpose

Staff inspect accountable redemptions and deliberately restore usage where authorized.

How It Works

Placement creates a redemption in the order transaction. Its retained terms and allocations explain the benefit on each line. Staff inspect uses through promotion, code or order lists and review aggregate performance. A deliberate release requires separate authority and a reason. Supported cancellation handling uses the retained release setting rather than later promotion configuration. Immutable records and referenced parents preserve the history behind reports. The product should settle performance definitions and prove cancellation behaviour across its orders-module dependency.

Relationships

The choose the best permitted promotional result capability supplies related configuration or assessment used in this work.

The prepare and control a promotion’s lifecycle capability supplies related configuration or assessment used in this work.

The issue promotion codes with controlled access 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: Each use is accounted for down to the line it discounted.A use is supplied back exclusively by an authorised person with an attributed reason, or by a cancellation the promotion allows.
Surfaces: consoleapi
Intent sources: services-commerce:docs/milestones/plans/COMM-M1-plan.md#2. Scope (item 6)services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D13services-commerce:docs/milestones/plans/COMM-M1-plan.md#4. Assumptions (A15)services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D-REC-11 (to confirm)

Controls

32 controls apply, from the corpus control catalogue.

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

Permissions

Key	Checked at	Scope
`commerce.promotions.read`	api	tenant
`commerce.promotions.override`	api	tenant

Business Rules

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

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Proposed	Order placement records redemption and increments code and promotion usage in the order transaction, freezing redemption terms and locking the promotion on first use. no proof recorded yet	invariant	service	test services-commerce:modules/promotions/tests/integration/services/persistence/promotion-redemptions.integration.spec.js#locks the promotion at its first redemption
`02`must prove Confirmed	Each order redeems a promotion at most once, and commit requires redemption totals and line discounts to agree with their allocations. origin: COMM-M1 D12 point 6 (docs/milestones/decisions/COMM-M1-D12-andrew-2026-10-19.md) no proof recorded yet	invariant	database	test services-commerce:modules/promotions/tests/integration/db/redemptions.table.integration.spec.js#refuses at COMMIT a redemption whose discount is not its allocations’ sum, naming the redemption
`03`must prove Proposed	Redemption amounts, snapshots and allocations are immutable, and applied status may become released without returning to applied. no proof recorded yet	invariant	database	test services-commerce:modules/promotions/tests/integration/db/redemptions.table.integration.spec.js#refuses moving a released redemption back to applied, SQLSTATE RHC04
`04`must prove Confirmed	Override permission and a reason allow one recorded release that restores code and promotion usage and appears in both histories. origin: COMM-M1 plan A15 (promotions D-06) (docs/milestones/plans/COMM-M1-plan.md) no proof recorded yet	permission	api, service	test services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#refuses a release without a reason, 400
`05`must prove Proposed	Full cancellation releases usage only under the redemption’s retained cancellation-release setting; partial cancellation and refund do not restore it. origin: COMM-M1 D13 (docs/milestones/COMM-M1-set-up-what-you-sell.md) no proof recorded yet	policy	service	documented services-commerce:docs/milestones/plans/COMM-M1-plan.md#D13. Restore a personal code when its order is cancelled?
`06`must prove Proposed	Redemption references protect their orders, promotions and codes from deletion and preserve redemption allocations. no proof recorded yet	invariant	database	test services-commerce:modules/promotions/tests/integration/db/redemptions.table.integration.spec.js#refuses deleting a promotion a redemption names, by promotion_redemptions_promotion_fk (RESTRICT)
`07`must prove Proposed	Performance groups monetary figures by currency and reports usage, remaining capacity, discounts, discounted-line revenue, refunds, credits and latest-checkout rejection reasons, excluding released uses. no proof recorded yet	calculation	service	test services-commerce:modules/promotions/tests/integration/services/persistence/promotion-statistics.queries.integration.spec.js#sums the discount given of the applied redemptions only: $5.00 and $3.00, not the released $10.00
`08` Proposed	Promotion, code and order redemption lists show newest uses first with line allocations and order numbers and totals. origin: COMM-M1 plan scope item 6 (docs/milestones/plans/COMM-M1-plan.md)	policy	service, console	test services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#lists the promotion’s redemptions newest first, each with its allocation
`09`must prove Proposed	Read permission covers redemption and performance inspection, while release requires override permission independently of manage or launch authority. no proof recorded yet	permission	api, console	test services-commerce:modules/promotions/tests/e2e/promotions-security.e2e.spec.js#cannot release a redemption, 403 permission_missing

Scenarios

Id	Given	When	Then	Provenance
`01`	The order has an applied code redemption	Release with a reason and repeat the request	Usage is restored with both histories recorded, and the second release fails	test services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#refuses the second release, 409 already_released
`02`	A personal single-use redemption retains enabled cancellation release	Cancel its order fully	The code becomes available for another use	documented services-commerce:docs/milestones/plans/COMM-M1-plan.md#D13. Restore a personal code when its order is cancelled?

Planning

Retain and review promotion usage ​

Purpose ​

How It Works ​

Relationships ​