Complete feature list, actor journeys, state flows, business rules, edge cases, and diagrams for the Promotion module.

Promotion Features and Flows

Use this page for the promotion domain: what it does for customers and admins, and how each flow behaves from start to finish.

1. Documentation Evidence

Source Type	Files or Docs	What Was Extracted
API	`apps/api/src/modules/promotion/customer/promotion-customer.controller.ts`, `admin/promotion-admin.controller.ts`	Routes, permissions, rate limits
Backend	`shared/promotion-evaluation.util.ts`, `promotion-evaluation.service.ts`, `promotion-redemption.service.ts`, `promotion-reconciliation.service.ts`	Derived lifecycle, selection order, gate, release, reconciliation
Schema	`packages/db/src/schema/promotion/{promotion,promotion-redemption,enums}.ts`	Rules as columns, basis points, CHECKs
Error registry	`apps/api/src/common/types/error-codes.ts` (`// PROMOTION`)	`PROMOTION_*` codes

2. Feature Summary

Field	Value
Module	`promotion`
Submodule	N/A
Primary user value	The customer gets the best available discount on their basket, with a clear reason when a coupon does not apply; the operator schedules and manages campaigns without a single "activate" job
Actors	Customer (signed in), admin, checkout (future)
Main entry points	`POST /api/mobile/promotions/evaluate`, `/api/admin/promotions` (6 routes)
Main outputs	Evaluation with applied/rejected promotions, reasons, savings; admin CRUD with a derived lifecycle badge
Related docs	API, Backend

3. Actor Matrix

Actor	Can Do	Cannot Do	Auth Requirement	Notes
Customer	Evaluate a coupon + automatic promotions against their live cart, with an optional district	Browse the promotion catalogue, consume usage limits by loading a page	JWT	`CUSTOMER_COUPON_ATTEMPT` 20/min account-keyed — a coupon code is a bearer value
Admin	List (derived-status filtered), detail, create, update (version required), retire, restore	Set a `status` — `state` is the only editable field	Admin JWT + `Promotions_*`	`pagination=false` accepted (the table is small)
Checkout (future)	Reserve / confirm / release redemptions	—	Internal	Must own the release edge incl. order cancellation

4. Capability Matrix

Capability	Surface	Actor	Route/Trigger	State Read	State Written	Linked API Section
Evaluate	Customer	Customer	`POST /api/mobile/promotions/evaluate`	live cart, promotions, district	—	API §4
Admin list	Admin	Admin	`GET /api/admin/promotions`	promotions (derived status)	—	API
Admin detail	Admin	Admin	`GET /:promotionId`	one promotion	—	API
Create	Admin	Admin	`POST /api/admin/promotions`	—	promotion row	API
Update	Admin	Admin	`PATCH /:promotionId`	row + version	promotion row	API
Retire	Admin	Admin	`DELETE /:promotionId`	row	`deleted_at` + coupon released	API
Restore	Admin	Admin	`POST /:promotionId/restore`	row	`deleted_at` cleared	API
Reserve/confirm/release	Internal	Checkout (future)	service calls	promotion + ledger	ledger rows, `usage_count`	backend §6

A customer enters a code at checkout. The backend normalises it (case-insensitive, whitespace-tolerant), evaluates it against the live cart, and returns applied + rejected promotions with reasons. Evaluation is a preview — nothing is redeemed, and no usage limit is consumed by loading a page.

Sequence Diagram

Branches and Edge Cases

Branch	Condition	Behavior	Error/Result
Ineligible coupon	Any rejection	200, not 4xx	`eligibility.valid: false` + `reason`
No coupon sent	`couponCode` omitted	Automatic promotions only	`eligibility.valid` = "any automatic applied"
No district + no default address	Free shipping applies	Value `null`	`shippingDiscount: null`
Unknown district	Explicit uuid names nothing	404	`SHIPPING_DISTRICT_NOT_FOUND`
Rejected draft/disabled/not_started	Lifecycle rejection	Blank name/type/discountType	Disclosure prevented
Expired coupon	Window passed	Not blanked	Named — support-answerable
Coupon + automatic both	Both apply	Best selection per type	`promotions.applied`

5.2 The derived lifecycle

`state` (stored)	clock	`status` (derived)
`draft`	—	`draft`
`disabled`	—	`disabled`
`published`	now < `startsAt`	`scheduled`
`published`	inside the window	`active`
`published`	now ≥ `endsAt`	`expired`

There is no "activate" button and no "expire" button. Publishing with a future start date IS scheduling. The admin form edits state; status is a read-only badge — a form that tries to PATCH a status is rejected.

5.3 Selection order

Eligible promotions sort by (priority DESC, computed discount DESC, id ASC). With every promotion at the default priority of 0, the customer gets best-value by default; a merchant raises priority to override. The id tiebreaker makes the order total — without it two equal candidates are ordered by whatever the planner returned. At most one promotion per type: one cart discount and one free shipping, never two of either.

6. Admin Flows

6.1 Create a promotion

Permission Promotions_CREATE, ADMIN_WRITE 10/min. Field rules the database enforces anyway (a 409 is a worse experience than a disabled submit button): promotionType ↔ discountType must agree (free_shipping on one requires it on the other); fixed_amount requires discountAmount and forbids discountPercentageBps; percentage requires discountPercentageBps (1–10000) and forbids discountAmount; free_shipping forbids both; maxDiscountAmount is percentage-only; omit couponCode for automatic (there is no isAutomatic flag); endsAt strictly after startsAt; usageLimitPerCustomer ≤ usageLimit.

6.2 Update — version required

PATCH requires version. A concurrent edit makes it stale → 409 PROMOTION_VERSION_CONFLICT with the current version in the message. Re-fetch and re-apply.

6.3 Retire and restore

DELETE is a soft delete. Redemption history is kept — a hard delete of anything redeemed is refused by the database — and the coupon code is released for reuse, so next year's campaign can reuse this year's code. Restore can fail with 409 PROMOTION_COUPON_CODE_TAKEN if another promotion claimed the code while this one was retired.

7. Lifecycle and State Transitions

Covered in §5.2 — the only stored transitions are draft → published, published → disabled, disabled → published, published → draft (editable). Everything else is derived from the clock.

9. Data and Side Effects by Flow

Flow	DB Writes	Cache Effects	Jobs	Realtime	Analytics	Notifications
Evaluate	—	—	—	—	—	—
Create/update	promotion row	automatic-set cache (30s)	—	—	—	—
Retire/restore	`deleted_at`	automatic-set cache	—	—	—	—
Reserve/confirm/release (future)	ledger rows, `usage_count`	automatic-set cache	sweep (lapsed holds)	—	—	—

10. Error and Recovery Flows

Scenario	Trigger	User/System Experience	Recovery	Source
Stale version	Concurrent operator	409 + current version	Re-fetch, re-apply	`PROMOTION_VERSION_CONFLICT`
Coupon code taken	Restore after reuse	409	Pick another code	`PROMOTION_COUPON_CODE_TAKEN`
Contradictory config	Bad field combo	409	Field rules	`PROMOTION_INVALID_CONFIGURATION`
Coupon rate limit	20/min exceeded	429	Retry after fixing the cart	`CUSTOMER_COUPON_ATTEMPT`
Lapsed holds	Abandoned checkouts	Total limit exhausted	Sweep job	reconciliation
Counter drift	Retried release	Downward drift	Ledger-gated release + reconciliation	redemption service

11. Diagrams Required Per Module

Actor capability diagram — §3/§4.
Sequence diagram per major flow — §5.1.
State machine diagram — §5.2.
Data side-effect diagram — §9.
Error branch diagram — §10.

12. Mandatory Feature and Flow Deep-Dive Pack

12.1 Feature Inventory With Minor Behaviors

Feature	Minor Behavior	Actor	Trigger	User/System Result	Backend Side Effect	Source
Evaluate	Normalisation	Customer	Mixed-case code	Upper-cased lookup	—	service
Evaluate	Blank rejected draft	Customer	Guessed code	Blank name/type	Disclosure prevented
Evaluate	`failedRules` all failures	Customer	Multiple misses	Every rule reported	—
Evaluate	`failedRules` empty on lifecycle	Customer	Expired coupon	No thresholds shown	—
Evaluate	`usageRemaining` only for named coupon	Customer	Automatic applies	Not broadcast	—
Evaluate	Selection changes with address	Customer	District added	Free shipping can outrank	—
Evaluate	Valid lines only	Customer	Invalid line in cart	Thresholds use valid subtotal	—
Admin list	Derived status filter	Admin	`?status=active`	SQL filter vs clock	—
Admin list	`pagination=false` accepted	Admin	List all	Small table	—
Admin list	Date-only `startsTo`	Admin	`2026-08-05`	Whole day	—
Retire	Coupon released	Admin	Delete	Reusable code	—
Restore	Code taken	Admin	Restore	409	—

12.2 Business Process Diagram Pack

12.3 Business Rules and Policy Traceability

Rule	Business Reason	Actor Impact	Enforced In	API Impact	Backend Impact	Tests
Lifecycle derived	No flip-job staleness	Never pays out after end	evaluation util	`status` computed	—	spec
Gate carries its own predicates	Evaluation is outside the lock	Pulled campaign never pays	gate SQL	—	reserve UPDATE	int spec
Release gated on ledger	Retry-safe	No double-decrement	redemption service	—	ledger transition	int spec
Two limits differ on expiry	Lapsed holds	Total limit needs sweep	per-customer count vs `usage_count`	—	sweep	int spec
Basis points	7.5% expressible	`750` = 7.5%	schema	`percentageBps`	CHECK	probe
Two nullable value columns	No polymorphic unit confusion	Type-driven columns	schema CHECK	—	—	probe
`coupon_code IS NULL` = automatic	No disagreeing flags	Single source	schema	—	—	probe
Selection `(priority, value, id)`	Best value by default	Total order	evaluation util	—	—	spec
Ineligible = 200	Business outcome	Branch on eligibility	service	—	—	spec
Blank rejected drafts	No disclosure	Generic message	service	—	—	spec

12.4 Tradeoffs and Product Rationale

Product Decision	User Benefit	Engineering Benefit	Alternative	Tradeoff	Risk
Derived lifecycle	Never stale payout	No cron flips	Stored status	Computed per read	Cheap
No `isAutomatic` flag	No disagreeing facts	One source	Flag	—	Documented
Basis points	Precision	Integer math	Whole percent	7.5% needs 750	Documented
Redemption internal-only	No page-load consumption	Frozen contract	HTTP endpoints	Checkout must call it	Prominent obligation
Coupon uncached	No 30s exploit window	Cache only automatic set	Cache both	Slower lookups	Accepted
Soft delete releases code	Reuse next year	Keep history	Hard delete	409 on restore	Documented

12.5 Flow Edge-Case Matrix

Flow	Edge Case	Trigger	Expected Behavior	User/System Feedback	Source
Evaluate	Unknown code	`not_found`	200 ineligible	"not valid"
Evaluate	Not started	`not_started`	200 + blank entry	"not started yet"
Evaluate	Superseded	Better same-type won	rejected with reason	Usually hidden
Evaluate	Exclusive conflict	Non-combinable	rejected	Usually hidden
Evaluate	No district	Free shipping	value null	"choose an address"
Evaluate	Invalid line	Archived product	Excluded from subtotal	—
Reserve	Already at limit	Usage exhausted	refused	`PROMOTION_USAGE_LIMIT_REACHED` (future)
Reserve	Pulled between eval + reserve	Operator edit	Gate refuses	—	predicates
Release	Retry	At-least-once	Single decrement	—	ledger gate
Reconcile	Concurrent reserve	During sweep	Counter not discarded	—	one statement
Restore	Code taken	Reused	409	PROMOTION_COUPON_CODE_TAKEN

12.6 Flow-to-Data Trace

Flow	Reads	Writes	Cache	Jobs/Events	Response Fields
Evaluate	cart, promotions, district	—	automatic set (read)	—	summary, discount, eligibility, promotions, metadata
Create/update	—	promotion	clear automatic	—	promotion response
Retire/restore	promotion	deleted_at	clear automatic	—	message/response
Reserve (future)	promotion	ledger + usage_count	clear	—	redemption

12.7 Experience Quality Checklist

The doc explains what the actor is trying to accomplish.
The doc explains what the backend does that the actor does not see (derived lifecycle, gate predicates, ledger).
The doc covers every minor flow and branch.
The doc includes user, admin and system flows.
The doc explains business logic, tradeoffs, and rationale.
The doc maps every flow to API routes and backend side effects.
The doc includes diagrams appropriate to each flow type.
The doc covers edge cases and failure recovery.

13. Completion Checklist

Every feature, minor action, and submodule capability is listed.
Every actor has allowed and forbidden behavior.
Every major and minor flow includes steps, branches, and diagrams.
Every lifecycle has a transition table and state diagram.
Every flow links to the API and backend docs.
TDD dependencies are called out where they shape behavior (no TDD pages published yet).

Promotion Features and Flows

Promotion Features and Flows

1. Documentation Evidence

2. Feature Summary

3. Actor Matrix

4. Capability Matrix

5. User-Facing Flows

5.1 Evaluate a coupon

Summary

Sequence Diagram

Branches and Edge Cases

5.2 The derived lifecycle

5.3 Selection order

6. Admin Flows

6.1 Create a promotion

6.2 Update — version required

6.3 Retire and restore

7. Lifecycle and State Transitions

9. Data and Side Effects by Flow

10. Error and Recovery Flows

11. Diagrams Required Per Module

12. Mandatory Feature and Flow Deep-Dive Pack

12.1 Feature Inventory With Minor Behaviors

12.2 Business Process Diagram Pack

12.3 Business Rules and Policy Traceability

12.4 Tradeoffs and Product Rationale

12.5 Flow Edge-Case Matrix

12.6 Flow-to-Data Trace

12.7 Experience Quality Checklist

13. Completion Checklist

See Also

On this page