Auto-Renewal

Overview

Auto-Renewal is an automated system that automatically renews subscribers' internet service when their package expires. Instead of manually activating each subscriber, the system runs in the background (via cron job) and automatically renews eligible subscribers, processes payments, and extends their service expiration.

WHAT IS AUTO-RENEWAL?

Auto-Renewal is an automated background process that:

Runs Every 15 Minutes - Checks for expiring subscribers
Automatic Activation - Renews without manual intervention
Smart Payment - Uses subscriber balance or creates due invoices
Error Handling - Skips failed subscribers, logs errors
Scalable Processing - Handles thousands of subscribers efficiently

Perfect for: Hands-free subscriber management, reducing manual work, ensuring uninterrupted service!

How Auto-Renewal Works

The Complete Flow

Every 15 Minutes:
1. Find Expiring Subscribers → 2. Validate Eligibility → 
3. Check Balances → 4. Generate Invoice → 5. Process Payment → 
6. Activate Service → 7. Send Notifications → 8. Log Results

Time Window

Auto-Renewal processes subscribers who:

Already Expired - Up to 1 month ago
Expiring Soon - Within next 15 minutes
Currently Expiring - Right now

Example:

Current Time: 10:00 AM
Processes subscribers expiring between:
- 9:00 AM (1 month ago) to 10:15 AM (15 minutes from now)

Cron Job Schedule

Runs Every 15 Minutes:

*/15 * * * * php /path/to/artisan autorenew:process

Why 15 Minutes?

Catches subscribers before they expire
Prevents service interruption
Balances system load
Ensures timely renewals

Eligibility Criteria

For a subscriber to be auto-renewed, ALL of the following must be true:

1. Subscriber Must Be Active

Status: Profile Status = 2 (Active)

Excluded:

Status 1: Pending
Status 3: Disabled
Status 4: Terminated
Status 5+: Other inactive

2. Subscriber Auto-Renewal Enabled

Setting: auto_renew_status ≠ 1 (or NULL)

Where to Set: Subscriber Profile → Auto-Renewal Settings

Values:

NULL or 0: Auto-renewal enabled ✅
1: Auto-renewal disabled (skip) ❌

3. Package Auto-Renewal Enabled

Setting: Package auto_renew_status = 1

Where to Set: Package Settings → Auto-Renewal Status

Values:

1: Auto-renewal enabled ✅
0 or NULL: Auto-renewal disabled ❌

4. Salesperson Active

Status: Salesperson Status = 1 (Active)

Excluded:

Status 0: Inactive
Status 2+: Other inactive states

5. Salesperson Auto-Renewal Enabled

Setting: Salesperson auto_renew_status ≠ 1 (or NULL)

Where to Set: User Profile → Auto-Renewal Settings

Values:

NULL or 0: Auto-renewal enabled ✅
1: Auto-renewal disabled (skip) ❌

6. Package Assigned to Salesperson

Requirement: Package must be allocated to salesperson in Package Accounting

Check: Package Accounting record exists for salesperson + package

7. No Recent Activation

Rule: Not activated in last 2 minutes

Checks:

last_activation_time > 2 minutes ago
auto_renew_last_activation_date > 2 minutes ago

Why: Prevents duplicate activations from concurrent processes

8. Expiration Within Time Window

Rule: Expiration date between 1 month ago and 15 minutes from now

Example:

Current: Jan 15, 2025 10:00 AM
Eligible: Expires between Dec 15, 2024 10:00 AM and Jan 15, 2025 10:15 AM

Auto-Renewal Process

Step 1: Find Eligible Subscribers

Query Filters:

Profile status = Active (2)
Subscriber auto-renewal enabled
Package auto-renewal enabled
Salesperson active and auto-renewal enabled
Expiration within time window
No recent activation (2-minute rule)

Result: List of eligible subscribers

Step 2: Process in Chunks

Chunk Size: 100 subscribers per batch

Why Chunking?

Prevents memory overflow
Handles thousands of subscribers
Better error isolation
Garbage collection between chunks

Example:

1000 subscribers found
→ Processed in 10 chunks of 100 each
→ Memory freed after each chunk

Step 3: Lock Subscriber Row

Transaction Safety:

Lock subscriber row with lockForUpdate()
Prevents concurrent processing
Ensures atomic operations
Other processes wait for lock

Step 4: Validate Subscriber

Checks:

Last invoice not within 2 minutes
Salesperson data valid
Package data valid
Package assigned to salesperson
Package accounting validation

If Fails: Skip subscriber, log error, continue to next

Step 5: Calculate Fees

Fee Calculation:

Package price (with pro-rating if applicable)
Extra fees (VAT, tax)
Subscriber discount
Net total

Pro-Rating:

If fixed expiry day enabled
Calculates partial month fees
Adjusts for remaining days

Step 6: Check Balances

Prepaid Package:

Check subscriber balance
Must have sufficient balance
If insufficient: Skip, log error

Postpaid Package:

Check subscriber balance first
If sufficient: Pay from balance
If insufficient: Check salesperson balance
Admin: No balance check

Step 7: Generate Invoice

Invoice Creation:

Package details
Fees and discounts
Expiration dates
Payment status (PAID or DUE)

Unique ID: Generated for tracking across all records

Step 8: Process Payment

Prepaid:

Always pay from subscriber balance
Invoice status: PAID
Salesperson profit: Added to balance

Postpaid (Subscriber Has Balance):

Pay from subscriber balance
Invoice status: PAID
Salesperson profit: Added to balance

Postpaid (Subscriber No Balance):

Create DUE invoice
Cut salesperson balance
Salesperson profit: In cash later

Step 9: Update Radius

Radius Activation:

Update expiration date
Set package speed limits
Update quota (if applicable)
Activate internet access

Step 10: Update Subscriber

Subscriber Updates:

Profile status: Active (2)
Package ID: Current package
Expiration date: New expiration
Last activation time: Now
Auto-renewal last activation: Now
Grace period: Reset
Quota: Updated

Step 11: Send Notifications

SMS Notification:

Template: Subscriber Activated
Details: Username, expiration date
Sent if SMS enabled

Email Notification:

Template: Subscriber Activated
Details: Username, expiration date, invoice
Sent if email enabled

Step 12: Log Activity

Activity Log:

Module: Subscriber Activation
Description: By Auto Renew
Subscriber ID and Invoice ID

System Log:

Success/failure status
Subscriber details
Fee amount
Expiration date

Payment Logic

Prepaid Packages

Always Use Subscriber Balance:

1. Check subscriber balance
2. If balance ≥ invoice amount:
   → Deduct from subscriber balance
   → Invoice status: PAID
   → Salesperson profit: Added to balance
3. If balance < invoice amount:
   → Skip subscriber
   → Log: Insufficient balance

Example:

Package Price: 1000 BDT
Subscriber Balance: 1500 BDT

Process:
- Deduct: 1500 - 1000 = 500 BDT
- Invoice: PAID
- Salesperson Profit: +100 BDT (to balance)

Postpaid Packages

Smart Payment Logic:

1. Check subscriber balance first
2. If subscriber balance ≥ invoice amount:
   → Pay from subscriber balance
   → Invoice status: PAID
   → Salesperson profit: Added to balance
3. If subscriber balance < invoice amount:
   → Check salesperson balance
   → If salesperson balance ≥ cost:
      → Cut salesperson balance
      → Invoice status: DUE
      → Salesperson profit: In cash later
   → If salesperson balance < cost:
      → Skip subscriber (unless admin)
      → Log: Insufficient balance

Example 1: Subscriber Has Balance

Package Price: 1000 BDT
Subscriber Balance: 1200 BDT
Salesperson Balance: 5000 BDT

Process:
- Pay from subscriber: 1200 - 1000 = 200 BDT
- Invoice: PAID
- Salesperson profit: +100 BDT (to balance)
- Salesperson balance: Unchanged

Example 2: Subscriber No Balance

Package Price: 1000 BDT
Subscriber Balance: 0 BDT
Salesperson Cost: 900 BDT
Salesperson Balance: 5000 BDT

Process:
- Subscriber balance: Unchanged (0)
- Salesperson balance: 5000 - 900 = 4100 BDT
- Invoice: DUE (1000 BDT)
- Salesperson profit: +100 BDT (in cash when subscriber pays)

Prepaid vs Postpaid

Comparison Table

Feature	Prepaid	Postpaid
Payment Source	Subscriber balance only	Subscriber balance OR salesperson balance
Balance Check	Subscriber balance required	Subscriber first, then salesperson
Invoice Status	Always PAID	PAID if subscriber has balance, else DUE
Salesperson Profit	Added to balance	Added to balance if paid, else in cash
Salesperson Balance	Not cut	Cut if subscriber has no balance
Skip if No Balance	Yes	No (creates DUE invoice)

When to Use Each

Use Prepaid When:

✅ Subscribers maintain prepaid balance
✅ Want guaranteed payment before service
✅ No credit/due invoices allowed
✅ Strict payment policy

Use Postpaid When:

✅ Subscribers pay monthly in cash
✅ Allow credit/due invoices
✅ Field staff collects payments
✅ Flexible payment terms

Balance Requirements

For Prepaid Packages

Subscriber Balance Required:

Subscriber Balance ≥ Invoice Amount

Example:
Invoice: 1000 BDT
Subscriber Balance: 1500 BDT ✅
Subscriber Balance: 800 BDT ❌ (Skipped)

No Salesperson Balance Check

For Postpaid Packages

Scenario 1: Subscriber Has Balance

Subscriber Balance ≥ Invoice Amount
→ No salesperson balance needed
→ Payment from subscriber

Example:
Invoice: 1000 BDT
Subscriber Balance: 1200 BDT ✅
Salesperson Balance: Not checked

Scenario 2: Subscriber No Balance

Subscriber Balance < Invoice Amount
→ Salesperson Balance ≥ Package Cost
→ Cut salesperson balance

Example:
Invoice: 1000 BDT
Subscriber Balance: 300 BDT
Salesperson Cost: 900 BDT
Salesperson Balance: 5000 BDT ✅
Salesperson Balance: 500 BDT ❌ (Skipped)

Admin Exception:

Admin can renew without balance check
Unlimited renewal power

Validation Rules

1. Rate Limiting (2-Minute Rule)

Rule: Cannot renew same subscriber twice within 2 minutes

Error: "Subscriber Already Activated X Seconds Ago. Minimum Interval: 120 Seconds"

Why: Prevents duplicate invoices from concurrent cron jobs

2. Package Accounting Validation

Rule: Package must pass accounting validation

Checks:

Package pricing configured
Extra fees valid
Discount rules valid

Error: Various validation errors

3. Balance Validation (Prepaid)

Rule: Subscriber must have sufficient balance

Error: "Insufficient Prepaid Subscriber Balance. Required: X BDT, Available: Y BDT"

4. Balance Validation (Postpaid)

Rule: Subscriber OR salesperson must have sufficient balance

Error: "Insufficient Postpaid Salesperson/Subscriber Balance"

5. Discount vs Profit Validation

Rule: Discount cannot exceed salesperson profit

Error: "Insufficient Profit Margin For Subscriber Discount. Discount: X BDT, Available Profit: Y BDT"

Why: Prevents negative profit scenarios

What Gets Skipped

Automatic Filtering (Query Level)

These subscribers are filtered out before processing:

Inactive Subscribers - Profile status ≠ 2
Subscriber Auto-Renewal Disabled - auto_renew_status = 1
Package Auto-Renewal Disabled - Package auto_renew_status ≠ 1
Inactive Salesperson - Salesperson status ≠ 1
Salesperson Auto-Renewal Disabled - Salesperson auto_renew_status = 1
Recent Activation - Activated within last 2 minutes
Outside Time Window - Not expiring within 1 month to 15 minutes

Result: Only eligible subscribers are loaded into memory

Processing-Level Skipping

These subscribers are skipped during processing:

Too Frequent Invoice - Invoice created within 2 minutes
Invalid Data - Missing salesperson or package
Invalid Package Accounting - Package not assigned to salesperson
Package Validation Failed - Accounting validation errors
Insufficient Balance - Prepaid or postpaid balance insufficient
Excessive Discount - Discount exceeds profit margin
Invoice Generation Failed - System error creating invoice

Result: Subscriber skipped, error logged, process continues

Failed Renewal Logs

What Gets Logged

For Each Failed Subscriber:

Subscriber ID
Subscriber Username
Error Message (detailed reason)
Timestamp
ISP/Branch ID
Status Flag

Log Location: Auto Renew Failed Logs

Common Error Messages

Balance Issues:

"Insufficient Prepaid Subscriber Balance. Required: 1000 BDT, Available: 500 BDT"
"Insufficient Postpaid Salesperson/Subscriber Balance"

Rate Limiting:

"Subscriber Already Activated 45 Seconds Ago. Minimum Interval: 120 Seconds"

Package Issues:

"Package 'Premium 10Mbps' Not Assigned To Salesperson 'reseller1'"
"Invoice Generation Failed For Package 'Basic 5Mbps'"

Validation Issues:

"Insufficient Profit Margin For Subscriber Discount. Discount: 150 BDT, Available Profit: 100 BDT"

Viewing Failed Logs

Location: Logs → Auto Renew Failed Logs

Configuration: Settings → Software Settings → Failed Auto Renew Log Status

Enable/Disable: Toggle logging on/off

Configuration

Enable/Disable Auto-Renewal

Package Level:

Go to Package Settings
Set "Auto Renew Status" = Enabled
Applies to all subscribers on this package

Subscriber Level:

Go to Subscriber Profile
Set "Auto Renew Status" = Enabled
Overrides package setting for this subscriber

Salesperson Level:

Go to User Profile (Salesperson/Reseller)
Set "Auto Renew Status" = Enabled
Applies to all their subscribers

Failed Log Configuration

Enable Logging:

Settings → Software Settings
"Failed Auto Renew Log Status" = Enabled
Logs all failed renewals

Disable Logging:

Set to Disabled
No failed logs created (saves database space)

Cron Job Setup

Add to Crontab:

bash

*/15 * * * * cd /path/to/zal-ultra && php artisan autorenew:process >> /dev/null 2>&1

Verify Running:

bash

crontab -l

Check Logs:

bash

tail -f storage/logs/laravel.log

Performance & Scalability

Chunked Processing

How It Works:

Processes 100 subscribers per chunk
Frees memory after each chunk
Prevents memory overflow
Handles unlimited subscribers

Example:

10,000 subscribers found
→ 100 chunks of 100 each
→ ~15 seconds per chunk
→ Total: ~25 minutes

Database Optimization

Query-Level Filtering:

Filters ineligible subscribers at database level
Only loads eligible subscribers into memory
Reduces RAM usage by 80%+
Faster processing

Row Locking:

Prevents concurrent processing
Ensures data integrity
Eliminates duplicate invoices

Eager Loading:

Pre-loads related data (package, salesperson, NAS)
Eliminates N+1 queries
Reduces database calls by 90%+

Memory Management

Garbage Collection:

Runs after each chunk
Frees unused memory
Prevents memory leaks
Stable long-term operation

Peak Memory Usage:

Typically 50-100 MB for 10,000 subscribers
Scales linearly with chunk size
Configurable chunk size

Performance Metrics

Typical Performance:

1,000 subscribers: ~2 minutes
10,000 subscribers: ~20 minutes
100,000 subscribers: ~3 hours

Factors Affecting Speed:

Server CPU and RAM
Database performance
Network latency (Radius)
SMS/Email sending
Concurrent load

Best Practices

For Admins

1. Enable Auto-Renewal Strategically

✅ Enable for stable packages
✅ Enable for reliable subscribers
❌ Disable for trial packages
❌ Disable for problematic subscribers

2. Monitor Failed Logs

✅ Check daily for failures
✅ Identify common issues
✅ Fix balance problems
✅ Adjust package settings

3. Maintain Salesperson Balances

✅ Keep balances topped up
✅ Monitor balance trends
✅ Set up balance alerts
✅ Add balance before month-end

4. Configure Cron Properly

✅ Run every 15 minutes
✅ Monitor cron execution
✅ Check system logs
✅ Verify renewals happening

For Resellers

1. Maintain Sufficient Balance

✅ Check balance regularly
✅ Top up before low
✅ Plan for month-end renewals
✅ Monitor balance deductions

2. Review Failed Renewals

✅ Check failed logs daily
✅ Identify subscribers with issues
✅ Top up subscriber balances
✅ Fix package assignments

3. Enable Auto-Renewal Wisely

✅ Enable for paying subscribers
✅ Disable for non-paying subscribers
✅ Review settings monthly
✅ Adjust based on payment behavior

For Subscribers

1. Maintain Prepaid Balance

✅ Keep balance above package price
✅ Top up before expiration
✅ Set up auto-top-up (if available)
✅ Monitor balance regularly

2. Ensure Auto-Renewal Enabled

✅ Check profile settings
✅ Verify auto-renewal status
✅ Contact ISP if disabled

Summary

Auto-Renewal is a powerful automated system that:

✅ Runs Automatically:

Every 15 minutes via cron
No manual intervention needed
Handles thousands of subscribers

✅ Smart Payment Logic:

Prepaid: Subscriber balance only
Postpaid: Subscriber first, then salesperson
Creates PAID or DUE invoices

✅ Robust Validation:

8+ eligibility criteria
7+ validation rules
Comprehensive error handling

✅ Error Handling:

Skips failed subscribers
Logs detailed errors
Continues processing others

✅ Transaction Safety:

Row locking prevents duplicates
Atomic operations
All-or-nothing per subscriber

✅ Scalable Performance:

Chunked processing
Memory management
Database optimization
Handles 100,000+ subscribers

Key Benefits:

Reduces manual work by 95%+
Ensures uninterrupted service
Automatic payment collection
Detailed audit trail
Scalable to any size

Perfect for ISPs wanting hands-free subscriber management with maximum reliability and minimal manual intervention!

Auto-Renewal ​

Overview ​

📋 Table of Contents ​

How Auto-Renewal Works ​

The Complete Flow ​

Time Window ​

Cron Job Schedule ​

Eligibility Criteria ​

1. Subscriber Must Be Active ​

2. Subscriber Auto-Renewal Enabled ​

3. Package Auto-Renewal Enabled ​

4. Salesperson Active ​

5. Salesperson Auto-Renewal Enabled ​

6. Package Assigned to Salesperson ​

7. No Recent Activation ​

8. Expiration Within Time Window ​

Auto-Renewal Process ​

Step 1: Find Eligible Subscribers ​

Step 2: Process in Chunks ​

Step 3: Lock Subscriber Row ​

Step 4: Validate Subscriber ​

Step 5: Calculate Fees ​

Step 6: Check Balances ​

Step 7: Generate Invoice ​

Step 8: Process Payment ​

Step 9: Update Radius ​

Step 10: Update Subscriber ​

Step 11: Send Notifications ​

Step 12: Log Activity ​

Payment Logic ​

Prepaid Packages ​

Postpaid Packages ​

Prepaid vs Postpaid ​

Comparison Table ​

When to Use Each ​

Balance Requirements ​

For Prepaid Packages ​

For Postpaid Packages ​

Validation Rules ​

1. Rate Limiting (2-Minute Rule) ​

2. Package Accounting Validation ​

3. Balance Validation (Prepaid) ​

4. Balance Validation (Postpaid) ​

5. Discount vs Profit Validation ​

What Gets Skipped ​

Automatic Filtering (Query Level) ​

Processing-Level Skipping ​

Failed Renewal Logs ​

What Gets Logged ​

Common Error Messages ​

Viewing Failed Logs ​

Configuration ​

Enable/Disable Auto-Renewal ​

Failed Log Configuration ​

Cron Job Setup ​

Performance & Scalability ​

Chunked Processing ​

Database Optimization ​

Memory Management ​

Performance Metrics ​

Best Practices ​

For Admins ​

For Resellers ​

For Subscribers ​

Summary ​

Auto-Renewal

Overview

📋 Table of Contents

How Auto-Renewal Works

The Complete Flow

Time Window

Cron Job Schedule

Eligibility Criteria

1. Subscriber Must Be Active

2. Subscriber Auto-Renewal Enabled

3. Package Auto-Renewal Enabled

4. Salesperson Active

5. Salesperson Auto-Renewal Enabled

6. Package Assigned to Salesperson

7. No Recent Activation

8. Expiration Within Time Window

Auto-Renewal Process

Step 1: Find Eligible Subscribers

Step 2: Process in Chunks

Step 3: Lock Subscriber Row

Step 4: Validate Subscriber

Step 5: Calculate Fees

Step 6: Check Balances

Step 7: Generate Invoice

Step 8: Process Payment

Step 9: Update Radius

Step 10: Update Subscriber

Step 11: Send Notifications

Step 12: Log Activity

Payment Logic

Prepaid Packages

Postpaid Packages

Prepaid vs Postpaid

Comparison Table

When to Use Each

Balance Requirements

For Prepaid Packages

For Postpaid Packages

Validation Rules

1. Rate Limiting (2-Minute Rule)

2. Package Accounting Validation

3. Balance Validation (Prepaid)

4. Balance Validation (Postpaid)

5. Discount vs Profit Validation

What Gets Skipped

Automatic Filtering (Query Level)

Processing-Level Skipping

Failed Renewal Logs

What Gets Logged

Common Error Messages

Viewing Failed Logs

Configuration

Enable/Disable Auto-Renewal

Failed Log Configuration

Cron Job Setup

Performance & Scalability

Chunked Processing

Database Optimization

Memory Management

Performance Metrics

Best Practices

For Admins

For Resellers

For Subscribers

Summary