User Story

I, as a Service Provider Marketing Manager, need to reward customers when they reach specific usage, activity, or payment milestones, so that I can increase customer loyalty, reduce churn, and recognize high-value customers without manual data analysis.

Example of use

1. Mobilix Telecom operates a prepaid mobile service with 250,000 subscribers. Their marketing team wants to reward loyal customers who use the service daily, re-engage customers showing signs of churn, and recognize high-value spenders with exclusive offers. Currently, the marketing team must export CDR data weekly, analyze it in spreadsheets, manually identify qualifying customers, and then trigger bonus credits—a process taking 15+ hours per week and always running days behind actual customer behavior. The marketing manager wants customers who meet specific criteria (e.g., "used service every day for 7 days", "spent over 50 EUR this month") to automatically receive their rewards.
2. GlobalConnect ISP serves 80,000 broadband and mobile customers. They want to implement a points-based loyalty program where customers earn rewards for consistent usage, timely top-ups, and reaching spending milestones. When a customer reaches a configured threshold, they should receive their reward (bonus minutes, data package, discount) and be notified about what they earned.

Business Model

Service providers (e.g. MVNOs) in competitive markets differentiate through customer experience and loyalty programs. Automatically rewarding customer behavior enables:

• Churn reduction: Re-engaging inactive customers before they port out; industry data suggests 15-25% of churning customers can be retained with timely intervention
• Revenue uplift: Rewarding high-value customers increases lifetime value; loyalty programs typically yield 5-15% revenue increase from engaged segments
• Operational efficiency: Eliminating manual weekly data exports and analysis saves 15+ hours/week for a marketing team of 3-4 people
• Customer satisfaction: Customers feel recognized and valued when rewards arrive promptly after achieving milestones

Technology

PortaBilling tracks customer behavior patterns based on rated usage sessions, payment transactions, and account activity. When configured thresholds are reached, customers receive rewards.

Current Solution

Today, service providers implement customer rewards through manual or semi-automated batch processes:

1. Billing Administrator exports CDR and payment data weekly from PortaBilling
2. Data analyst imports data into spreadsheet or BI tool
3. Analyst runs queries to identify customers meeting various criteria (e.g., inactive 7+ days, high spenders, frequent top-ups)
4. Marketing team manually creates customer segments
5. Administrator manually applies bonus credits or discounts to qualifying accounts
6. Rewards reach customers 3-7 days after they actually achieved the milestone

Limitations and pain points:

• Delayed gratification: Customer uses service for 7 consecutive days but doesn't receive reward until the following week—missing the psychological moment of achievement
• Inconsistency: Different analysts may apply criteria differently; some qualifying customers may be missed
• Scalability: Manual process breaks down beyond 50,000 customers; larger operators cannot feasibly analyze all accounts weekly
• No continuous tracking: Cannot track ongoing patterns like "consecutive days of usage" without complex custom scripts
• Churn before intervention: By the time inactivity is identified, customers may have already switched to competitors

Stakeholders and Their Benefits

• Marketing Manager – Configures reward thresholds and corresponding benefits once; customers automatically receive rewards when qualifying; can design loyalty tiers knowing they will work consistently
• Customer – Receives rewards promptly upon reaching milestones; feels valued through timely recognition rather than delayed generic campaigns
• Finance Director – Reduces churn-related revenue loss; gains predictable loyalty program costs tied to actual customer value metrics
• Billing Administrator – Configures thresholds and rewards in PortaBilling admin interface; eliminates repetitive data export and manual bonus application tasks
• Customer Service Representative – Can see customer's loyalty status and earned rewards; can explain program to customers during support call

Use Cases

Use Case #1: Consecutive Activity Streak Rewards

Business Need: Service provider wants to reward customers who demonstrate consistent daily engagement with the service, encouraging habit formation and reducing churn risk.

Preconditions:

• Customer "Maria Silva" (Customer ID 100089) with active prepaid account 2000555
• Account has product "Prepaid Mobile Plus" with voice, SMS, and data services
• Service Provider has configured activity streak rewards:
  • 7 consecutive days of activity → 50 bonus minutes
  • 30 consecutive days of activity → 200 bonus minutes + 500 MB data
• Activity is defined as any rated usage session (voice call, SMS, or data session)
• Reward rules are applied to account 2000555 and other configured accounts

Role:

• Service Provider
• Customer

Use scenario #1.1: Customer reaches 7-day consecutive usage streak and receives reward

1. At 2025-02-21, Service Provider configures activity streak rewards for specified customer segment including account 2000555
2. At 2025-03-01 08:15:00, Maria makes a 3-minute voice call; day 1 of streak
3. At 2025-03-02 12:30:00, Maria sends 2 SMS messages; day 2 of streak
4. At 2025-03-03 09:45:00, Maria uses 50 MB mobile data; day 3 of streak
5. At 2025-03-04 18:20:00, Maria makes a 5-minute call; day 4
6. At 2025-03-05 14:00:00, Maria uses 100 MB data; day 5
7. At 2025-03-06 11:30:00, Maria sends 1 SMS; day 6
8. At 2025-03-07 16:45:00, Maria makes a 2-minute call; day 7
9. Customer reaches 7-day streak threshold

Expected result:

• Customer receives 50 bonus minutes credited to account 2000555
• Customer receives notification about the reward (e.g., "Congratulations! You've used our service for 7 days in a row. Here's 50 bonus minutes as a thank you!")
• Streak counter continues tracking toward 30-day tier
• 7-day reward does not trigger again until streak resets (due to missed day) and customer reaches 7 days again

Use scenario #1.2: Customer reaches higher streak tier (30 days) and receives premium reward

1. Continuing from scenario #1.1, Maria maintains daily usage through March 2025
2. Maria already received 7-day reward on 2025-03-07
3. Maria continues daily usage pattern through 2025-03-30
4. At 2025-03-30 19:20:00, Maria makes evening call; streak reaches 30 days

Expected result:

• Customer receives 200 bonus minutes + 500 MB data credited to account 2000555
• Customer receives notification about premium reward achievement
• Previous 7-day reward does not re-trigger (already granted for this streak)

Use scenario #1.3: Customer breaks streak and restarts

1. Maria had 25-day streak as of 2025-03-25
2. Maria does not use any service on 2025-03-26 (no calls, SMS, or data)
3. Streak resets to 0
4. At 2025-03-27, Maria resumes usage; new streak begins at day 1
5. Maria maintains daily usage through 2025-04-02 (7 days)

Expected result:

• 7-day reward triggers again (50 bonus minutes) since this is a new streak
• Customer receives notification about reaching 7-day milestone again
• Previous partial progress toward 30-day tier is lost; counter starts fresh

Use Case #2: Inactivity Win-Back Incentives

Business Need: Service provider wants to re-engage customers who have stopped using the service by offering them incentives before they churn to a competitor.

Preconditions:

• Customer "Jan Kowalski" (Customer ID 100156) with active prepaid account 2000777
• Account balance: 12.50 EUR
• Last rated usage session: 2025-04-01 14:30:00 (5-minute voice call)
• Service Provider has configured inactivity win-back incentives:
  • 7 days inactive → 10 bonus minutes + SMS reminder
  • 14 days inactive → 50 bonus minutes + personalized offer
  • 30 days inactive → 100 bonus minutes + 200 MB data

Role:

• Service Provider
• Customer

Use scenario #2.1: Customer receives win-back incentive after inactivity period

1. At 2025-04-01 14:30:00, Jan makes his last voice call (5 minutes to domestic number)
2. Days pass with no usage from account 2000777
3. On 2025-04-08, 7 full days have passed since last usage

Expected result:

• Customer receives 10 bonus minutes credited to account 2000777
• Customer receives win-back message (e.g., "We miss you, Jan! Here's 10 bonus minutes. Your balance of 12.50 EUR is waiting for you.")
• 7-day incentive recorded; will not repeat unless customer resumes and then becomes inactive again

Use scenario #2.2: Escalating incentives for continued inactivity

1. Customer "Ahmed Hassan" (Customer ID 100234) last used service on 2025-05-01
2. On 2025-05-08, customer receives 7-day win-back incentive (10 bonus minutes)
3. Customer does not resume usage
4. On 2025-05-15, customer receives 14-day incentive (50 bonus minutes + personalized offer)
5. Customer still does not resume usage
6. On 2025-06-01, customer receives 30-day incentive (100 bonus minutes + 200 MB data)

Expected result:

• Three separate incentives granted at each threshold (7, 14, 30 days)
• Each incentive includes progressively more valuable reward
• Messages become more urgent/personalized at higher tiers
• If customer resumes usage at any point, inactivity tracking resets

Use Case #3: Welcome-Back Recognition

Business Need: Service provider wants to acknowledge when previously inactive customers return to the service, reinforcing their decision to come back and measuring win-back campaign effectiveness.

Preconditions:

• Customer "Jan Kowalski" (Customer ID 100156) with prepaid account 2000777
• Customer was inactive and received win-back incentive on 2025-04-08
• No usage sessions recorded between 2025-04-01 and 2025-04-12
• Service Provider has configured welcome-back bonus: 20 bonus minutes for customers returning after 7+ days of inactivity

Role:

• Service Provider
• Customer

Use scenario #3.1: Previously inactive customer returns and receives welcome-back bonus

1. Customer received win-back incentive on 2025-04-08 (7-day inactivity)
2. At 2025-04-12 09:30:00, Jan makes a 2-minute voice call (first usage in 11 days)

Expected result:

• Customer receives 20 bonus minutes as welcome-back reward
• Customer receives message (e.g., "Welcome back, Jan! Great to see you again. Here's 20 bonus minutes on us.")
• Inactivity counter resets; new activity streak may begin
• Service provider can correlate return with win-back campaign for effectiveness measurement

Use Case #4: Spending Milestone Rewards

Business Need: Service provider wants to recognize and reward customers who reach spending milestones within a billing period, creating tiered loyalty status and encouraging continued spending.

Preconditions:

• Customer "Sofia Andersson" (Customer ID 100412) with postpaid account 2001000
• Billing period: monthly (1st to last day of month)
• Current period: 2025-06-01 to 2025-06-30
• Cumulative spend as of 2025-06-14: 47.30 EUR
• Service Provider has configured spending rewards:
  • 50 EUR/month → Bronze status + a free ticket
  • 100 EUR/month → Silver status + a Netflix subsription
  • 200 EUR/month → Gold status + a digital voucher

Role:

• Service Provider
• Customer

Use scenario #4.1: Customer crosses spending milestone and receives tier reward

1. At 2025-06-15 10:00:00, Sofia makes 15-minute international call charged at 0.25 EUR/min = 3.75 EUR
2. Cumulative spend for period: 47.30 + 3.75 = 51.05 EUR
3. Customer crosses 50 EUR threshold

Expected result:

• Customer receives Bronze status for current period
• Customer receives email: "Congratulations Sofia! You've reached Bronze status this month. Enjoy a free ticket for the upcoming Yankees game!"
• Sofia receives an electronic ticket to the football game
• 100 EUR and 200 EUR thresholds remain active for potential upgrade this period

Use scenario #4.2: Customer reaches top-tier spending

1. Continuing from scenario #4.1, Sofia's cumulative spend reaches 198.50 EUR by 2025-06-28
2. At 2025-06-28 16:30:00, Sofia uses roaming data (2.50 EUR charge)
3. Cumulative spend: 198.50 + 2.50 = 201.00 EUR
4. Customer crosses 200 EUR threshold

Expected result:

• Customer upgraded to Gold status (supersedes Bronze)
• Customer receives notification about premium tier achievement
• Sofia receives a free monthly Netflix subscription

Use Case #5: Destination-Based Usage Rewards and Alerts

Business Need: Service provider wants to recognize customers with significant usage to specific destination groups (e.g., international calling) and offer them relevant plan upgrades or cost-saving alternatives.

Preconditions:

• Customer "Carlos Mendes" (Customer ID 100523) with prepaid account 2001111
• Customer is on domestic plan but occasionally uses international calling
• Service Provider has configured destination group "International Premium" (ID 500):
  • 10 EUR spend → Offer upgrade to International Plan (saves customer money if usage continues)
  • 25 EUR spend → Reward with EUR 5 that can be spent for international calls valid for 10 days
• Current international premium spend: 7.25 EUR

Role:

• Service Provider
• Customer

Use scenario #5.1: Customer exceeds international calling threshold and receives targeted offer

1. At 2025-07-10 19:00:00, Carlos makes 12-minute call to premium international destination (0.35 EUR/min = 4.20 EUR)
2. Cumulative international premium spend: 7.25 + 4.20 = 11.45 EUR
3. Customer crosses 10 EUR threshold for destination group "International Premium"

Expected result:

• Customer receives targeted message: "Carlos, we noticed you make international calls regularly. Upgrade to our International Plan for 15 EUR/month and save up to 40% on these calls!"
• Offer includes easy upgrade path (reply YES or click link)
• If customer continues without upgrading and reaches 25 EUR, they are rewarded with EUR 5 they can spent on international calls within next 10 days

Use scenario #5.2: Customer exceeds roaming threshold and receives cost-control notification

1. Customer "Yuki Tanaka" (Customer ID 100678) traveling abroad
2. Service Provider has configured roaming alert at 500 MB: notify customer + offer roaming package
3. Roaming data used since trip start: 480 MB
4. At 2025-08-05 14:20:00, Yuki streams video using 35 MB roaming data
5. Cumulative roaming data: 515 MB

Expected result:

• Customer receives proactive notification: "You've used 515 MB of roaming data. To avoid unexpected charges, consider our Traveler Package: 2 GB for 20 EUR."
• Customer can purchase package directly from the mobile self-care
• Prevents bill shock and demonstrates provider cares about customer's costs

Use Case #6: Lifetime Value Recognition

Preconditions:

• Customer "Priya Sharma" (Customer ID 100789) with prepaid account 2001222
• Account created on 2025-01-15
• Total top-ups to date: 485.00 EUR across 12 transactions
• Service Provider has configured lifetime top-up rewards:
  • 100 EUR lifetime → "Regular" badge
  • 500 EUR lifetime → "Loyal Customer" badge + permanent 3% bonus on all top-ups
  • 1000 EUR lifetime → "VIP" badge + permanent 5% bonus + priority support

Role:

• Service Provider
• Customer

Use scenario #6.1: Customer reaches lifetime top-up milestone

1. At 2025-09-01 11:30:00, Priya tops up 20.00 EUR via mobile app
2. Cumulative lifetime top-ups: 485.00 + 20.00 = 505.00 EUR
3. Customer crosses 500 EUR lifetime threshold

Expected result:

• Customer receives "Loyal Customer" badge/status on account
• Customer receives a digital voucher for the partner shopping center
• Customer receives notification: "Thank you for your loyalty, Priya! You've reached Loyal Customer status. Enjoy the shopping with this digital voucher!"
• 1000 EUR threshold remains active for future VIP upgrade

Use Case #7: Top-Up Frequency Rewards

Preconditions:

• Customer "Lisa Chen" (Customer ID 100901) with prepaid account 2001333
• Service Provider has configured frequency reward: 5 top-ups within 30-day rolling window → 10% bonus on next top-up + auto-recharge offer

• Current 30-day window (2025-08-29 to 2025-09-28): 4 top-ups recorded

Role:

• Service Provider
• Customer

Use scenario #7.1: Customer reaches top-up frequency threshold

1. Previous top-ups in current 30-day window: 4 transactions on 2025-09-03, 2025-09-10, 2025-09-17, 2025-09-22
2. At 2025-09-28 13:45:00, Lisa makes 5th top-up of 15.00 EUR

Expected result:

• Customer receives 10% bonus on current top-up (15.00 EUR → 16.50 EUR credited)
• Customer receives message: "You top up often, Lisa! We've added 10% extra to this top-up. Want to set up auto-recharge and never worry about running low?"
• Frequency counter continues rolling

Use Case #8: Payment Reminder Before Balance Exhaustion

Business Need: Service provider wants to remind customers who haven't topped up recently but are still actively using service, preventing service interruption and improving customer experience.

Preconditions:

• Customer "Thomas Müller" (Customer ID 101123) with prepaid account 2001444
• Last payment (top-up): 2025-08-15 for 25.00 EUR
• Current balance: 3.20 EUR (low)
• Customer has been actively using service (daily calls consuming balance)
• Service Provider has configured: no payment for 30 days + balance < 5 EUR + active usage → send top-up reminder with bonus offer

Role:

• Service Provider
• Customer

Use scenario #8.1: Active customer with low balance receives top-up reminder

1. Last payment date: 2025-08-15
2. On 2025-09-14, 30 days have passed since last payment
3. Customer has balance of 3.20 EUR
4. Customer has been actively using service (usage recorded in last 7 days)

Expected result:

• Customer receives reminder: "Thomas, your balance is 3.20 EUR. Top up now and get 10% extra!"
• Message includes easy top-up options (link, USSD code, etc.)
• Bonus offer (10% extra) incentivizes immediate top-up
• Prevents service interruption for engaged customer

Use scenario #8.2: Distinguishing inactive from active low-balance customers

1. Customer "Anna Schmidt" (Customer ID 101456) has not topped up in 45 days
2. Customer has NOT used service in 30 days (no calls, SMS, data)
3. Balance: 8.50 EUR

Expected result:

• Customer is treated as inactive (Use Case #2), not as "needs top-up reminder"
• Customer receives win-back incentive, not top-up reminder
• Message acknowledges absence rather than assuming active engagement

Non-functional requirements

Peculiarities

• Marketing departments come up with different campaigns really often, so service providers need flexibility, e.g. start tracking customer usage/behavior and apply new actions without having to update PortaBilling
• Existing loyalty solutions (e.g. https://www.saasquatch.com) suggest that BSS can send web events, so that they can apply rules/actions (see https://docs.saasquatch.com/integrations)

Performance / Clustering, Geo Redundancy/ Dual-Version, Porter / Call Control API / ESPF / Monitoring

Idempotency:

• Same threshold crossing emits only one event per reset period
• Event includes unique event_id (UUID) for deduplication by middleware