PRD: Promotions, methods & segment rules

Module	Pricing	PRD ID	PRD-PROMO-001
Status	Ready to dev	FEAT	PROMO
Epic	—	Plane	BANA-1573
Date	2026-06-15	Version	v1.0
Packages	@nx/pricing	URD	PROMO
Surface	Client · Owner/Mgr
Owner	Phát Nguyễn

What promotions, methods & segment rules are

This feature lets a merchant configure a discount campaign as one self-contained object: a promotion carries exactly one method - fixed amount or percentage; aimed at line items, the whole order, or shipping; spread per item, across items, or once - and a scheme: a straight discount (standard) or a buy-X-get-Y deal (buy-get). Three rule sets segment the campaign: eligibility decides who/when qualifies, source decides what must be bought, target decides what gets discounted. The whole graph - promotion, method, all three rule sets - is created and edited in one atomic aggregate; stored rule counts are set at create time and not yet recomputed on aggregate update.

Applying the discount at checkout is a deliberate later increment; this PRD specifies the promotion configuration aggregate - promotion, method, and three rule sets.

Why a first-class promotion object is needed

Pricing already selects fares (FARE) and computes taxes (TAX), but a merchant had no way to express a discount campaign - "10% off drinks before 5pm", "buy 2 coffees get 1 free", "50,000₫ off orders over 300,000₫". A campaign is not a fare: it spans more than one line, it can target the order or shipping rather than an item, and it must say not just how much to discount but who qualifies, what triggers it, and what it lands on.

Without a first-class promotion object an owner cannot build these offers at all, and the data needed to apply them at checkout does not exist. This increment closes the configuration gap: it gives the owner a promotion with one method, a standard or buy-get scheme, and three distinct rule sets, all authored and edited as one atomic unit - so a campaign is always saved complete or not at all, never half-built.

One example, start to finish

Step	What happens	Result
An owner creates the "Buy 2 coffees, get 1 free" promotion	One request: a buy-get scheme, one percentage method valued 100 targeting items (source-min 2, target 1), one source rule (the qualifying drink), one target rule (the free drink), one eligibility rule limiting it to the dine-in channel	The promotion, its method, and all three rules are saved together in one atomic call; the rule counts read back correctly
Later the owner edits the campaign	An aggregate update: drop the channel rule, raise the usage limit	All changes are saved in one single atomic save

The easiest thing to get wrong

Rule counts do not update themselves when the aggregate is edited

Eligibility / source / target rule counts are written once, at create time. A later aggregate update - adding, changing, or removing rules - does not recompute these numbers, so the displayed count can drift from the rules actually stored after an edit.

1. Goals & Non-Goals

Goals

• A promotion object with a scheme (standard or buy-get), a code or automatic trigger, an effective window, a usage limit, and a lifecycle status.
• Exactly one method per promotion declaring the mechanic: fixed or percentage, a target (items / order / shipping), an allocation (per item / across items / once), and a discounted-quantity cap.
• Buy-get support: a method that declares a source minimum quantity (must buy) and a target quantity (gets discount).
• Three segment rule sets - eligibility (on the promotion), source and target (on the method) - reusing the shared rule model (attribute, operator, value, AND logic).
• One atomic aggregate create and update across promotion + method + all rule sets, with stored rule counts set on create (not yet recomputed on update) and a shape-based rule merge on update.
• Cascade removal that removes the method and every attached rule with the promotion.

Non-Goals

• Applying promotion discounts during checkout pricing - the calculator is not yet wired into either simulation pipeline (URD-PROMO-006, still a Won't this increment).
• Fare selection and tax computation - owned by FARE and TAX.
• Multi-currency conversion of discount amounts (a currency and exchange rate are carried, not converted here).
• Order persistence, invoice issuance, stock or payment side effects.

2. Success Metrics

Metric	Target / signal
Atomicity	A failed sub-step (missing rule field, absent method) leaves nothing persisted
Aggregate completeness	Every saved promotion has exactly one method; rule sets persist together with it
Count accuracy	Eligibility / source / target rule counts match the stored rules at create time; on aggregate update the counts are not yet recomputed and may drift
Edit integrity	An aggregate update creates, updates, and deletes rules in one atomic save by entry shape
Code integrity	No two live promotions in the same merchant share a code (target design - see Risks)

3. Personas & Scenarios

Persona	Goal in this feature
Owner / Manager	Build a discount campaign - pick the mechanic, the target, and the rules that segment it
Marketing staff	Author time-boxed offers (happy-hour, weekday, channel-specific) and retire them via status
System (future checkout)	Read a complete, valid promotion graph to apply at the point of sale (later increment)

Core scenario: an owner creates a "Buy 2 coffees, get 1 free" promotion - a buy-get scheme, one percentage method valued 100 targeting items with source-min 2 and target 1, one source rule (the qualifying drink) and one target rule (the free drink), plus an eligibility rule limiting it to the dine-in channel. The promotion, its method, and all three rules are saved in one atomic call; the rule counts read back correctly. Later the owner edits the aggregate to drop the channel rule and raise the usage limit - all in one atomic save.

4. User Stories

#	As a	I want	So that
01	owner	to create a promotion, its method, and all its rules in one request	a campaign is never saved half-built
02	owner	to choose a fixed amount or a percentage and aim it at the items, the order, or shipping	the offer matches what I am promoting
03	owner	to build a buy-X-get-Y deal by setting the source quantity to buy and the target quantity to discount	classic combo offers are possible
04	marketing staff	to segment an offer with eligibility, source, and target rules	it fires only for the right basket on the right channel
05	marketing staff	to retire an offer by moving its status to deactivated or expired	it stops without being deleted
06	owner	to edit an existing promotion's rules - adding, changing, and removing them - in one save	maintenance is a single atomic step

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	A promotion, its single method, and its rule sets are created together in one atomic aggregate.	✅	URD-PROMO-001
FR-002	A promotion has at most one method.	✅	URD-PROMO-003
FR-003	The method discounts by a fixed amount or by a percentage, and carries the matching discount value.	✅	URD-PROMO-008
FR-004	The method targets one of three things: line items, the order, or shipping.	✅	URD-PROMO-009
FR-005	The method declares how the discount is allocated. • Three allocations: per item, spread across items, or once for the whole group. • The method can cap the quantity eligible for the discount.	✅	URD-PROMO-010..011
FR-006	A promotion is either standard or buy-get. • A standard promotion discounts the chosen target directly. • A buy-get method declares a source-minimum quantity and the target quantity given away.	✅	URD-PROMO-007 · URD-PROMO-012
FR-007	Three rule sets segment a campaign. • Eligibility rules sit on the promotion: who and which orders qualify. • Source rules sit on the method: which items count as the purchase. • Target rules sit on the method: which items are discounted or given away. • All three reuse the same shared rule model.	✅	URD-PROMO-013 · URD-PROMO-004
FR-008	Eligibility / source / target rule counts are stored on the promotion. • The counts are set when the aggregate is created. • They are not yet recomputed on aggregate update, so they can drift once rules are edited.	🔶	URD-PROMO-014
FR-009	A promotion carries three control attributes. • An optional unique code; with no code entered, the system generates one. • A flag for whether the promotion stacks with other promotions. • A flag for whether the discount value already includes tax.	✅	URD-PROMO-015..016
FR-010	A promotion carries an effective window, a usage limit, and a running usage count.	✅	URD-PROMO-017
FR-011	A promotion moves through lifecycle statuses, defaulting to draft.	✅	URD-PROMO-018
FR-012	An aggregate update merges the rules in one atomic save. • Each submitted rule entry reads as a create, an update, or a delete based on its own shape. • The save either lands in full or changes nothing.	✅	URD-PROMO-019 · URD-PROMO-002
FR-013	Deleting a promotion cascades to its method and every attached rule, atomically.	✅	URD-PROMO-020
FR-014	Promotions, methods, and rules are confined to the user's own merchant, and deletion is a soft-delete.	✅	URD-PROMO-005

5.1 Acceptance Criteria

• Send a create-aggregate request with a method and its rules in one call → the promotion, method, and every rule are saved together; leave a required field blank on one of the rules in that same request → the whole request is refused and nothing is saved.
• Send a create-aggregate request with two methods for the same promotion → the request is refused, a promotion holds exactly one method.
• Create a method of type fixed with a value of 50,000₫, or type percentage with a value of 20 → the method saves the exact type and discount value entered.
• Create a method targeting items, then another targeting the order, then another targeting shipping → all three targets save and read back correctly.
• Create a method with an across allocation and a discounted-quantity cap of 3 → the method applies the across allocation and never discounts more than 3 units.
• Create a buy-get promotion whose method declares a source-min quantity of 2 and a target quantity of 1 → the method saves both quantities; create a standard promotion without buy-get quantities → the method saves normally without those two fields.
• Create a promotion with one eligibility rule, one source rule, and one target rule in the same request → all three rules save, correctly distinguished by context (eligibility on the promotion, source/target on the method).
• Create a promotion with 2 eligibility rules → the eligibility rule count reads back as 2; update the aggregate to add a third eligibility rule → the new rule saves but the count still reads 2, not reflecting the rule just added.
• Create a promotion without entering a code → it saves as automatic, with no code; create another promotion with code "SUMMER10", the stacking flag on, and the tax-inclusive flag on → all three fields save correctly.
• Create a promotion with an effective window from date A to date B and a usage limit of 100 → all three fields save; read back the running usage count → it defaults to 0.
• Create a new promotion without passing a status → the status defaults to draft; update the status to activated, then to deactivated → each transition follows the lifecycle.
• Update the aggregate with one rule with no id, one rule with an id and updated fields, and one rule with only an id → the first rule is created, the second is updated, the third is deleted, all in one save.
• Delete a promotion that has a method and attached rules → the method and every rule are deleted with it, leaving no orphan records.
• Log in as merchant X's owner and list promotions → only merchant X's promotions come back; delete a promotion and list again → it no longer appears, though the record still exists in the system (soft delete).

6. Non-Functional Requirements

Area	Requirement
Atomicity	The whole campaign graph - promotion, method, eligibility / source / target rules - is one all-or-nothing save
Tenancy & authz	All operations confined to the user's own merchant, authenticated and gated by promotion / method / rule permissions
Validation	A rule created during an aggregate write must carry attribute, operator, and data type, or the whole write is refused
Consistency	Stored rule counts are set inside the create aggregate's atomic save; aggregate update does not yet recompute them
Precision	Discount value, max quantity, and buy-get quantities use 4-decimal precision
i18n	Promotion name and description are bilingual

7. UX & Flows

The configuration surface lets the owner pick the scheme, set the code (or leave it automatic), define the effective window and usage limit, choose the method's mechanic / target / allocation, enter buy-get quantities, and attach the three rule sets. Editing reuses the same aggregate; status moves a campaign through its lifecycle without deletion.

8. Data & Domain

Concept	Role in this feature
Promotion	The campaign - scheme, code/automatic, stacking, tax-inclusive, effective window, usage limit/count, status; holds the eligibility rules
Promotion method	The single mechanic - fixed/percentage value, target type, allocation, discounted-quantity cap, buy-get source-min and target quantities
Rule	A polymorphic condition (attribute, operator, value, priority); attached to the promotion (eligibility) or the method (source / target, distinguished by context)

Conceptual only - full schema and invariants live in the pricing domain model. A method's source and target rules are the same concept distinguished by a stored context tag; integrity is enforced by the aggregate logic, not by database constraints.

9. Dependencies & Assumptions

Depends on

#	Feature	Dependency
01	PROMO Shared rule model	Eligibility, source, and target rules reuse the same attribute / operator / value shape with AND logic; the same model is also used by FARE (URD-PROMO-004).
02	Commerce / Merchant	Every promotion, method, and rule is confined to the user's own merchant.
03	Shared pricing model	Promotion, method, and rule definitions, schemes, and status values.

Assumptions

#	Assumption	If wrong
01	A promotion has exactly one method; multi-method campaigns are out of scope.	A merchant needing several methods on one promotion cannot be represented by the current model and must split the offer into separate promotions.
02	Source and target rules are meaningful only for buy-get-style mechanics; standard promotions typically use eligibility rules alone.	Declaring source/target rules on a standard promotion has no effect, because the standard mechanic never reads those two rule sets.
03	The checkout-time calculator that consumes this configuration is a separate, later increment.	If the checkout calculator does not honor this exact aggregate shape once wired in, a configuration-valid campaign could still apply incorrectly at checkout.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P3 - see URD feature catalog
Rollout	All merchants; no feature flag
Migration	None - new promotion / method / rule data; no change to existing fare/tax data
Launch criteria	Aggregate create persists promotion + one method + all rule sets atomically; counts read back correctly; aggregate update merges rules by shape; delete cascades; codes unique per merchant (target design)
Monitoring	Aggregate create/update error rate by reason (missing rule field, absent method, code conflict)

References

• URD: Pricing - PROMO
• Sibling PRD: Fare & Tax Pricing Engine
• Module: Pricing - URD
• Developer: @nx/pricing · Promotion System · @nx/core

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Partial campaign on failure (promotion without a method, or with orphan rules)	Whole graph is one atomic save - any failure rolls back fully
02	Rule counts drift from the rules actually stored	Counts are set inside the create aggregate's atomic save; aggregate update does not yet recompute them, so counts can drift after an edit that adds or removes rules (known gap)
03	Ambiguous edit intent (add vs change vs remove a rule)	Aggregate update is shape-based: no id creates, id+fields updates, id only deletes
04	Two live promotions reuse a code	The code-uniqueness constraint is currently system-wide (not scoped to a merchant), so two merchants cannot yet reuse the same code; the target design is a code unique per merchant, and the merchant must be added to the constraint (known gap)
05	Owner expects the discount to apply at checkout	Out of scope this increment - the calculator is not yet wired (URD-PROMO-006)

FAQ

#	Question	Answer
01	Does creating a promotion apply a discount at checkout?	No - this increment ships the configuration surface only. The calculator that applies promotions during pricing is a separate, later increment (URD-PROMO-006).
02	How many methods can a promotion have?	Exactly one. The mechanic (fixed/percentage, target, allocation, buy-get quantities) all lives on that single method.
03	What is the difference between the three rule sets?	Eligibility rules (on the promotion) decide who/when qualifies; source rules (on the method) decide what must be bought; target rules (on the method) decide what gets discounted. Source and target are the same rule concept distinguished by a stored context tag.
04	How do I edit a campaign's rules?	Send an aggregate update - a rule with no id is created, a rule with id and fields is updated, a rule with only an id is deleted, all in one atomic save.
05	What happens to the method and rules when I delete a promotion?	They are cascade-deleted with it atomically - no orphan method or rules are left behind.
06	What does a promotion with no code mean?	It is automatic (auto-apply) only. A code, when present, is unique among live promotions; the target design is unique per merchant.