Rhythm 2.0 Specifications

Appearance

CAP-COM-CAT-014Prepare and control a promotion’s lifecycle

Markdown

CAP-COM-CAT-014

Prepare and control a promotion’s lifecycle

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-COM-CAT-04
Key concepts
CON-COM-CAT-005
Actors
ACT-COM-001, ACT-COM-002, ACT-COM-004, ACT-COM-007
Journeys
JNY-COM-CAT-004
Depends on
CAP-COM-CAT-005
Related
CAP-COM-CAT-015, CAP-COM-CAT-016, CAP-COM-CAT-017
Proved by
ATS-COM-CAT-014

KindCapabilityProduct areaCommerceModuleCatalog and Selling ConfigurationRevision1

Read atservices-commerce c8b66a98react-console baf6dae3

Prepare and control a promotion’s lifecycle ​

Purpose ​

Staff configure marketing offers and administrators authorize their launch.

How It Works ​

A coordinator creates a draft and chooses its claim mode and benefits. Parts refer to selling areas whose providers validate their criteria. The editor collects usage, dates, combination and eligibility choices for review. Activation has a separate permission and checks whether the offer is operationally complete. Subsequent lifecycle actions retain reasons in history. Redemption locks economic terms while allowing supported maintenance. Staff can end and duplicate an offer when its substance needs to change. The product should complete the revised milestone’s verification before approving these contracts.

Relationships ​

The organize product shelves 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.

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

The retain and review promotion usage capability supplies related configuration or assessment used in this work.

The Formal Contract

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

Outcomes
An offer is fully described prior to it can go live.Once used, an offer’s money terms does not permit silently change.Campaign preparation and activation require distinct authority.
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#D12services-commerce:docs/milestones/COMM-M1b-promotions-and-codes.md#Decisions (D-R1, D-R2, R6)services-commerce:docs/milestones/plans/COMM-M1b-engine.md#1. Routes and shapes (for the console job)

Controls

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

Permissions

KeyChecked atScope
commerce.promotions.readapitenant
commerce.promotions.manageapitenant
commerce.promotions.activateapitenant

Business Rules

14 rules, 10 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.

IdRuleKindEnforced atProvenance
01must prove
Proposed
Promotions are automatic or code-claimed; automatic promotions cannot hold codes and a coded draft cannot change to automatic.
origin: COMM-M1 plan A16 (docs/milestones/plans/COMM-M1-plan.md)
no proof recorded yet
policyservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses to make a draft with a code automatic, 409 automatic_promotion_has_no_codes
02must prove
Proposed
An offer uses one to twenty selling-area parts or one order-level amount or shipping benefit, never both, and percentage or per-unit benefits require parts.
origin: COMM-M1b D-R1 (docs/milestones/COMM-M1b-promotions-and-codes.md)
no proof recorded yet
validationapi, servicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses parts together with an order-total offer, 400 promotion_invalid in plain words
03must prove
Proposed
Selling applications validate their parts’ areas and criteria, with percentages limited to one hundred percent and positive fixed amounts requiring currency.
origin: COMM-M1b D-R1 (docs/milestones/COMM-M1b-promotions-and-codes.md)
no proof recorded yet
validationservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses a product that is not merchandise, 400 promotion_invalid naming the part and the product
04must prove
Proposed
A stated discount cap is at least one minor unit and limits all parts together; minimum purchase uses qualifying lines and validation reports all discovered promotion problems together.
origin: COMM-M1 plan A19 (Q07) (docs/milestones/plans/COMM-M1-plan.md)
no proof recorded yet
validationapi, service, databasetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#names every problem of a sloppy promotion in one 400 promotion_invalid, the zero cap among them (Q07, journey 0203)
05must prove
Proposed
Code eligibility belongs to individual codes, promotion eligibility is limited to automatic promotions, and legacy scope values are accepted without effect.
origin: COMM-M1b D-R2 (docs/milestones/COMM-M1b-promotions-and-codes.md)
no proof recorded yet
validationservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses a promotion-level eligibility rule on a code-claimed promotion, 400 in the code’s words
06must prove
Proposed
Audience-price combination is enabled by default and remains changeable after redemption.
origin: COMM-M1 D12, D12-F2 (docs/milestones/COMM-M1-set-up-what-you-sell.md)
no proof recorded yet
policyservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#defaults "combine with audience prices" to yes when the body leaves it out (D12)
07
Confirmed
New promotions default to exclusive stacking, automatic priority one hundred and the internal name as their customer-facing name.
origin: COMM-M1 plan A15, A16 (promotions D-02, Q03); COMM-M1b R6 (docs/milestones/plans/COMM-M1-plan.md)
policyservice, consoletest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#defaults public_name to the name
08
Proposed
Promotion names are unique ignoring case, and each promotion receives a displayed promotion number.
validationservice, databasetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses a name another promotion of the tenant has, whatever its case, 409 promotion_name_taken
09must prove
Proposed
Permitted lifecycle moves are draft to active, active to paused and back, active or paused to ended, and draft or ended to archived; refused moves identify both states and successful moves retain reasons in history.
origin: COMM-M1 plan scope item 6 (docs/milestones/plans/COMM-M1-plan.md)
no proof recorded yet
lifecycleservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses every operation from a state it does not move, 409 invalid_transition
10must prove
Proposed
Activation requires an offer, currency for monetary benefits, a rule for selected eligibility and an active code for code-claimed promotions.
no proof recorded yet
lifecycleservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#refuses to activate a coded promotion with no active code, 409 no_active_code
11must prove
Confirmed
Activation and resumption require launch permission separately from management permission for preparation, pausing, ending, archiving and duplication.
origin: COMM-M1 plan A15 (promotions D-06) (docs/milestones/plans/COMM-M1-plan.md)
no proof recorded yet
permissionapi, consoletest
services-commerce:modules/promotions/tests/e2e/promotions-security.e2e.spec.js#cannot activate a draft, 403 permission_missing
12must prove
Proposed
First redemption locks the promotion’s economic configuration, identifying changed locked fields and directing staff to end and duplicate it; names, dates and limits remain editable.
no proof recorded yet
lifecycleservice, databasetest
services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#names the column and offers to end the promotion and duplicate it
13
Proposed
Duplication creates a newly named and numbered draft with copied configuration, no codes or uses, and history identifying its source.
lifecycleservicetest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#copies no code and no use
14
Proposed
Promotions remain retained through ending or archiving rather than deletion.
lifecycleapiobserved
react-console:lib/authz/backend-aliases.ts:COMMERCE_KEYS_WITHOUT_BACKEND

Scenarios

IdGivenWhenThenProvenance
01The coordinator holds management permission without launch authorityCreate a draft and request activationPreparation succeeds and activation fails permission evaluationtest
services-commerce:modules/promotions/tests/e2e/promotions-security.e2e.spec.js#cannot activate a draft, 403 permission_missing
02A promotion already has redemptionsChange its benefit and then extend its datesThe locked economic change fails while the date change savestest
services-commerce:modules/promotions/tests/e2e/promotion-redemptions.e2e.spec.js#refuses the new benefit value, 409 promotion_locked
03A promotion has percentage Books and per-unit Apparel partsRead back the promotionParts retain position order and the first part is mirrored in the promotion-level benefit fieldstest
services-commerce:modules/promotions/tests/e2e/promotions.e2e.spec.js#repeats part 1 in the promotion’s own benefit

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software