--- id: CAP-COM-CAT-017 title: Retain and review promotion usage feature: FEAT-COM-CAT-04 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f 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#D13' - 'services-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) purpose: >- Staff inspect accountable redemptions and deliberately restore usage where authorized. 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. concepts: - CON-COM-CAT-005 actors: - ACT-COM-001 - ACT-COM-004 surfaces: - console - api permissions: - key: commerce.promotions.read where_checked: api scope: tenant - key: commerce.promotions.override where_checked: api scope: tenant rules: - id: BR-CAP-COM-CAT-017-01 statement: >- Order placement records redemption and increments code and promotion usage in the order transaction, freezing redemption terms and locking the promotion on first use. kind: invariant enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/promotions/tests/integration/services/persistence/promotion-redemptions.integration.spec.js#locks the promotion at its first redemption origin: none - id: BR-CAP-COM-CAT-017-02 statement: >- Each order redeems a promotion at most once, and commit requires redemption totals and line discounts to agree with their allocations. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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 origin: >- COMM-M1 D12 point 6 (docs/milestones/decisions/COMM-M1-D12-andrew-2026-10-19.md) - id: BR-CAP-COM-CAT-017-03 statement: >- Redemption amounts, snapshots and allocations are immutable, and applied status may become released without returning to applied. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- services-commerce:modules/promotions/tests/integration/db/redemptions.table.integration.spec.js#refuses moving a released redemption back to applied, SQLSTATE RHC04 origin: none - id: BR-CAP-COM-CAT-017-04 statement: >- Override permission and a reason allow one recorded release that restores code and promotion usage and appears in both histories. kind: permission enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#refuses a release without a reason, 400 origin: COMM-M1 plan A15 (promotions D-06) (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-017-05 statement: >- Full cancellation releases usage only under the redemption’s retained cancellation-release setting; partial cancellation and refund do not restore it. kind: policy enforced_at: - service must_prove: true provenance: documented source: >- services-commerce:docs/milestones/plans/COMM-M1-plan.md#D13. Restore a personal code when its order is cancelled? origin: COMM-M1 D13 (docs/milestones/COMM-M1-set-up-what-you-sell.md) note: Cancellation proof belongs to the orders module’s acceptance work. - id: BR-CAP-COM-CAT-017-06 statement: >- Redemption references protect their orders, promotions and codes from deletion and preserve redemption allocations. kind: invariant enforced_at: - database must_prove: true provenance: test source: >- 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) origin: none - id: BR-CAP-COM-CAT-017-07 statement: >- 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. kind: calculation enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none note: Product confirmation of performance definitions remains outstanding. - id: BR-CAP-COM-CAT-017-08 statement: >- Promotion, code and order redemption lists show newest uses first with line allocations and order numbers and totals. kind: policy enforced_at: - service - console must_prove: false provenance: test source: >- services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#lists the promotion’s redemptions newest first, each with its allocation origin: COMM-M1 plan scope item 6 (docs/milestones/plans/COMM-M1-plan.md) - id: BR-CAP-COM-CAT-017-09 statement: >- Read permission covers redemption and performance inspection, while release requires override permission independently of manage or launch authority. kind: permission enforced_at: - api - console must_prove: true provenance: test source: >- services-commerce:modules/promotions/tests/e2e/promotions-security.e2e.spec.js#cannot release a redemption, 403 permission_missing origin: none scenarios: - id: SC-CAP-COM-CAT-017-01 given: The order has an applied code redemption when: Release with a reason and repeat the request then: >- Usage is restored with both histories recorded, and the second release fails provenance: test source: >- services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#refuses the second release, 409 already_released - id: SC-CAP-COM-CAT-017-02 given: A personal single-use redemption retains enabled cancellation release when: Cancel its order fully then: The code becomes available for another use provenance: documented source: >- services-commerce:docs/milestones/plans/COMM-M1-plan.md#D13. Restore a personal code when its order is cancelled? depends_on: - CAP-COM-CAT-016 related: - CAP-COM-CAT-014 - CAP-COM-CAT-015 journeys: - JNY-COM-CAT-005 open_questions: - OQ-COM-CAT-004 evidence: - >- Pinned service inputs: modules/promotions/aws/api/promotion-redemptions.routes.ts, promotions.routes.ts (redemptions, performance, history); services/persistence/promotion-redemptions.ts, promotion-statistics.ts; services/redemptions/**; db/promotion-redemptions.table.ts, order-line-discounts.table.ts, checkout-promotions.table.ts, promotion-events.table.ts; tests (redemptions e2e, persistence, queries, statistics, table, concurrency) - >- Pinned console inputs: components/commerce/promotions/{redemptions-tab,performance-tab}.tsx; components/commerce/order-flows/release-use-dialog.tsx (Order 360, owned by the orders module) 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-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] --- # 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.