--- id: CON-COM-CAT-005 name: Promotion feature: FEAT-COM-CAT-04 product_area: commerce module: catalog revision: 1 status: draft product_intent: confirmed implementation_evidence: partially-observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A promotion is a configured marketing benefit applied automatically or claimed by code, with qualification, combination and usage controls. owned_by: MOD-COM-CAT synonyms: - Coupon (Rhythm 1.0) - Discount - 'Offer (in the sense of a promotional offer, not a recommendation)' not_to_be_confused_with: - 'An audience price, which is a purchaser’s normal price, not a discount' - A contextual product suggestion - A later Accounting reversal or repayment facets: - name: Kind meaning: Automatic and code-claimed kinds determine how assessment begins. used_for: Whether buyers require a code. - name: Parts and order-level offers meaning: Parts and order-level offers define the covered lines and amounts. used_for: Selecting the covered benefit. - name: Combining rules meaning: >- Audience combination, stacking, priority, caps and minimums govern competition. used_for: Assessing permitted alternative combinations. - name: Code meaning: 'Identity, dates, restrictions, ownership and limits control claims.' used_for: Controlling claim qualification and capacity. - name: Code generation batch meaning: Background batches generate and export codes. used_for: Distributing generated claims. - name: Redemption and allocation meaning: Retained terms and line allocations explain each placed use. used_for: Retaining usage and monetary allocation evidence. - name: Lifecycle and history meaning: 'Lifecycle records distinguish preparation, launch and later actions.' used_for: Reviewing campaign actions and activation. - name: Performance meaning: Usage and monetary aggregates support campaign review. used_for: Inspecting campaign outcomes. relationships: - to: CON-COM-CAT-004 statement: >- A promotion discounts the price the calculation returned, on the audience basis or the Standard basis. provenance: documented source: >- services-commerce:docs/milestones/decisions/COMM-M1-D12-evaluation-algorithm.md#2. Two bases per line (D12 point 7) - to: CON-COM-CAT-003 statement: >- Merchandise parts are limited by product and category, and a product excluded from promotions is does not discounted. provenance: test source: >- services-commerce:modules/promotions/tests/unit/pricing/parts.spec.js#leaves a line excluded from promotions out of every part, whatever the provider says lifecycle: - state: Draft meaning: Preparation state before sale-time application. how_it_changes: Launch occurs under activation authority. - state: Active meaning: The offer participates during its permitted interval. how_it_changes: Customer customer staff pause or end it. - state: Paused meaning: Temporarily not applied; uses retained. how_it_changes: 'An administrator resumes or activates it, or customer staff end it.' - state: Ended meaning: The offer stops while retaining its campaign and usage history. how_it_changes: Customer customer staff archive it. - state: Archived meaning: The terminal archived state removes ordinary-list visibility. how_it_changes: Final. acted_on_by: - CAP-COM-CAT-014 - CAP-COM-CAT-015 - CAP-COM-CAT-016 - CAP-COM-CAT-017 - CAP-COM-CAT-018 visible_to: - ACT-COM-001 - ACT-COM-002 - ACT-COM-004 - ACT-COM-005 evidence: - >- Pinned service inputs: modules/promotions (promotions, parts, codes, issuances, evaluation library, redemptions, previews, statistics), COMM-M1 D12 and its algorithm, D13, COMM-M1b D-R1 to D-R4 - 'Pinned console inputs: components/commerce/promotions/**' supersedes: [] --- # Promotion ## What It Is A promotion describes a marketing offer the customer wants Commerce to consider during a sale. It gives staff a named place to specify the benefit, the lines it covers and the conditions under which it can be used. An automatic offer enters assessment without a buyer typing anything; a code-claimed offer is requested by entering an associated code. The offer can cover several selling-area parts or a single order-level benefit. Each part connects its criteria to the application that understands those items. This lets Commerce coordinate the discount without taking ownership of every application’s product classification. Customer-facing naming helps the resulting explanation communicate the offer rather than an internal campaign reference. A promotion has a lifecycle as well as economic configuration. Staff prepare drafts, administrators launch them and later actions retain history. Once an order uses the offer, its redemption captures the terms and line allocations for that use. The current promotion remains available for inspection without changing the economic history already retained on an order. ## What It Is Not A promotion differs from an audience price, a code and a refund. A code is a claim mechanism with its own restrictions and capacity. Audience pricing can exist without any campaign. Releasing a redemption restores usage under explicit authority; returning money follows the order’s accounting workflow and does not itself establish that a promotion use is available again. ## How It Is Used Coordinators prepare offers and codes and use Try It on sample carts. Administrators review prerequisites before launching. Buyers see the calculation’s selected benefit and explanation, which may show that their audience pricing is better than the entered code. Staff later inspect redemptions and performance or release a use with a reason. Validation, launch permission and locked economic terms can all prevent a proposed change. ## Its Facets **Claim mode.** Automatic and code-claimed kinds determine how assessment begins. **Benefits.** Parts and order-level offers define the covered lines and amounts. **Combination.** Audience combination, stacking, priority, caps and minimums govern competition. **Codes.** Identity, dates, restrictions, ownership and limits control claims. **Issuance.** Background batches generate and export codes. **Redemptions.** Retained terms and line allocations explain each placed use. **History.** Lifecycle records distinguish preparation, launch and later actions. **Performance.** Usage and monetary aggregates support campaign review. ## How It Relates Promotions consume the calculated prices and selling-area qualification supplied by other capabilities. Orders carry their redemptions, line allocations and customer explanations. Accounting receives invoice descriptions and later supplies financial facts used in performance. Eligibility controls permitted subjects independently of combination rules. ## What It Could Become The product should resolve outstanding recommendations about code characters, unapplied claims and performance definitions. It should clarify mixed personal and shared cancellation-release defaults and finish verification of the revised parts model before approving its design.