loyalty-agent-service/docs/specs/reward_campaign/pool_definition.md

title, type, status, domain

title	type	status	domain
Pool Definition	OpenSpec	Draft	Reward Campaign Management

Pool Definition

Requirement Definition

Defines Reward Pools which track stored values (Points, Cash Rebates, Lucky Draw chances, eVouchers). Pools dictate expiry policies, entity tracking levels (Customer, Account, Card), and velocity controls.

Process Flow

Pre-Conditions

• Users must have access rights.
• Pool Conversion Rate must be active.
• Account Type Groups (if applicable) must be active.

Business Rules

Data Schema

General Information

Field Name	Description	Logic Type	Constraints / Rules
Pool Id	System-generated identifier.	String (10)	Required.
Pool Name	Name of the pool.	String (30)	Required.
Pool Type	Points, Cash Rebate, Lucky Draw, eVoucher.	Enum	Required.
Expiry Policy	Method to calculate expiry date.	Enum (Lookup)	Required (except eVoucher).
Policy Parameter N	Numeric parameter for Expiry Policy.	Integer	Conditional based on policy.
Expiry Date	Fixed expiry date.	Date	Conditional (if policy is Fixed Date).
Ripening Period	Days before reward is redeemable.	Integer	Conditional. Default 0.
Conversion Rate Code	Currency representing a unit of reward.	Enum (Lookup)	Conditional.
Allow Negative Balance	Allow pool to go negative on adjust/cancel.	Boolean	Conditional. Default False.
Precision	Number of decimal places.	Enum (Lookup)	Conditional. Default 2.
Account Type Group	Restricts earning to specific accounts.	Enum (Lookup)	Optional.
Grace Period	Months to keep expired buckets before forfeit.	Integer	Optional.
Entity Level	Tracks balance at Customer, Account, Card.	Enum	Required.

Product Specific Policy

Overrides general expiry policy for specific Account Types.

Field Name	Description	Logic Type	Constraints / Rules
Product Account Level	PAL.	Enum (Lookup)	Required.
Product Account Type	PAT.	Enum (Lookup)	Required. Unique per row.
Expiry Policy	Specific expiry policy.	Enum (Lookup)	Required.

Velocity Control

Defines thresholds for sending alerts (Exception Alert Reports).

Field Name	Description	Logic Type	Constraints / Rules
Maximum	Threshold limit.	Decimal	Required.
Transaction Type	Award, Redeem, Adjust.	Enum	Required.
Units	Per Pool Units or Per Transaction.	Enum	Required.
Per Entity 1	Customer, Account, Card.	Enum	Optional (System-wide if null).
Per Entity 2	Corporation, Chain, Store, Terminal.	Enum	Optional.
Per Period	Quarter, Month, Week, Day.	Enum	Required.
Alert Template	Message template for alert.	Enum	Required.
Alert Group	Recipient group (SMS/Email).	Enum	Required.

Execution

• Precision cannot be reduced after transactions are posted.
• Entity Level cannot be moved downwards (e.g., Customer to Card) after transactions are posted.
• Evoucher pools have No Expiry, no Precision, and no Negative Balances.

Exception Flow

• N/A