Appearance
Retroactive Points
Overview
Retroactive Points is a one-time feature that allows you to award loyalty points to customers for actions they completed before your loyalty program was active or before specific earning rules were enabled. This ensures existing customers are fairly rewarded for their past loyalty.
This feature is designed for merchants who just installed the Keystone Loyalty Rewards app and want to recognize their customers' historical engagement with the store.
One-Time Feature
Retroactive Points is meant to be used once after installing the app. After the retroactive points job completes, the feature will be dismissed from the UI and cannot be run again. If you don't need this feature (e.g., you imported customer balances from another app), you can decide not to use the feature.
Supported Earning Rules
Retroactive points can be awarded for the following earning rules:
| Earning Rule | What is Awarded |
|---|---|
| Orders | Points for past orders based on your current Order Earning Rule configuration |
| Signup | Points for account creation based on your current Signup Earning Rule configuration |
| Newsletter | Points for newsletter subscriptions based on your current Newsletter Earning Rule configuration |
Note: Each retroactive earning rule uses the exact same configuration and calculation logic as the corresponding active earning rule.
Configuration
Prerequisites
Before you can run retroactive points:
- Loyalty program must be enabled
- All selected earning rules must be enabled and configured
- Customer sync job must be complete (happens automatically after app installation)
Selecting Earning Rules
Choose which earning rules to apply retroactively:
- Orders - Award points for past purchases
- Signup - Award points for existing customer accounts
- Newsletter - Award points for existing newsletter subscribers
You can select one, multiple, or all earning rules.
Time Period Selection
Define how far back to award points:
| Option | Description | Example |
|---|---|---|
| All Time | Award points for all historical data | From store opening to now |
| Custom Period | Specify start and end dates | Last 12 months, Last 24 months |
Default: All Time
Customer Notifications
Email Notifications
Customers will be automatically notified about their retroactive points if the Retroactive points earned email notification is enabled. This email notification can be configured in Email Notifications > Retroactive points earned.
If enabled, customers receive an email showing:
- Total retroactive points awarded
- Which earning rules were applied
- Their updated point balance
- How to view their full transaction history
Processing Details
Orders Earning Rule
When processing retroactive order points:
- Query all customer orders within the selected time period
- Apply your current Order Earning Rule configuration:
- Purchase type filter (one-time, subscription, both)
- Points per order calculation
- Points per currency calculation
- Order value components (subtotal, savings, taxes, shipping)
- Minimum and maximum thresholds
- Create transactions tagged as
retroactive - Update customer point balances
- Send email notification (if enabled)
Signup Earning Rule
When processing retroactive signup points:
- Query all customers who created accounts within the selected time period
- Apply your current Signup Earning Rule configuration:
- Points per signup
- Create transactions tagged as
retroactive - Update customer point balances
- Send email notification (if enabled)
Newsletter Earning Rule
When processing retroactive newsletter points:
- Query all customers who subscribed to the newsletter within the selected time period
- Apply your current Newsletter Earning Rule configuration:
- Points per newsletter signup
- Create transactions tagged as
retroactive - Update customer point balances
- Send email notification (if enabled)
Transaction Tagging
All retroactive transactions are tagged with retroactive to distinguish them from ongoing earning activities:
| Field | Value |
|---|---|
| Transaction Type | Earning Rule name (e.g., "Order Earning Rule") |
| Points | Calculated points |
| Tags | retroactive |
| Original Date | Date of original action (order date, signup date, etc.) |
| Processed Date | When retroactive points were applied |
Generated Reports
After processing completes, two CSV reports are automatically generated:
1. Customer Balances Report
Shows each customer's updated point balance:
| Column | Description |
|---|---|
| Customer ID | Shopify customer ID |
| Customer Name | Customer's name |
| Customer Email | Customer's email address |
| Previous Balance | Points before retroactive award |
| Retroactive Points | Points added retroactively |
| New Balance | Total points after retroactive award |
2. Transactions Report
Lists all retroactive transactions per customer:
| Column | Description |
|---|---|
| Customer ID | Shopify customer ID |
| Customer Email | Customer's email address |
| Transaction ID | Unique transaction identifier |
| Earning Rule | Which rule was applied |
| Original Date | Date of original action |
| Points Awarded | Points for this transaction |
| Order ID | Order number (if applicable) |
| Tags | Transaction tags |
Report Storage
- Format: CSV files
- Storage Duration: 30 days
- Access: Email notification
- Automatic Deletion: Files are deleted after 30 days
Setup Process
Step 1: Enable Loyalty Program
- Complete the initial app setup
- Enable your Loyalty Program
- Configure earning rules you plan to use
- Wait for customer sync to complete
Step 2: Access Retroactive Points
- Navigate to Loyalty Program in the Keystone Loyalty Rewards App
- You'll see a Retroactive Points prompt
- Click Configure Retroactive Points
Step 3: Select Earning Rules
Choose which earning rules to apply:
- Orders
- Signup
- Newsletter
Only enabled earning rules can be selected.
Step 4: Set Time Period
Choose your time period:
- All Time (default)
- Custom date range
Step 5: Configure Email Notifications (Optional)
Navigate to Email Notifications > Retroactive points earned to:
- Enable or disable customer notifications
- Customize the email content
- Preview the notification email
Recommended
Enable email notifications to inform customers about their retroactive points award. This helps build excitement and engagement with your new loyalty program.
Step 6: Start Processing
Click Start Retroactive Points to begin.
One-Time Action
This action cannot be undone. Once started, you cannot run retroactive points again. Review your configuration carefully before proceeding.
Step 7: Download Reports
After completion:
- Download Customer Balances CSV
- Download Transactions CSV
- Review customer point updates
The feature will then be dismissed from your UI.
Validation Rules
Before starting the retroactive points job, the system validates:
- Loyalty Program Status: Must be enabled
- Selected Earning Rules: Must be enabled and configured
- Customer Sync Status: Must be complete
- Previous Retroactive Run: Must not have been run before
- Time Period: Must be valid date range
If any validation fails, the system will display an error message and prevent the job from starting.
Use Cases
1. New Loyalty Program Launch
Scenario: First-time loyalty program installation
Strategy:
- Select: Orders, Signup, Newsletter
- Time Period: All Time
- Result: All existing customers receive points for past activities
Benefits:
- Existing customers feel valued
- Immediate point balances encourage engagement
- Fair treatment across all customers
2. Limited Historical Rewards
Scenario: Large store with long history wants to limit liability
Strategy:
- Select: Orders only
- Time Period: Last 12 months
- Result: Recent orders are rewarded, older history excluded
Benefits:
- Controlled point liability
- Focuses on currently active customers
- Manageable processing time
3. Migration from Another Platform
Scenario: Switching from a different loyalty app
Strategy:
- Dismiss Retroactive Points feature
- Import customer balances directly using data import
- Result: Customer balances preserved from previous platform
Benefits:
- No duplicate point awards
- Seamless transition
- Maintains customer trust
Best Practices
1. Review Your Point Liability
Calculate the cost before running retroactive points:
Example Calculation:
├─ Historical orders: 5,000
├─ Average order value: $75
├─ Total order value: $375,000
├─ Points per $1: 10
├─ Total points to award: 3,750,000
├─ Redemption value: 1 point = $0.01
└─ Estimated liability: $37,5002. Consider Your Timeframe Carefully
Factors to consider:
- Store age and order volume
- Current loyalty program budget
- Active vs. inactive customer ratio
- Average order frequency
3. Enable Rules Before Running
Ensure all earning rules you want to apply retroactively are:
- Enabled in the app
- Properly configured
- Tested with new orders first
4. Communicate with Customers
If you enabled the Retroactive Points Earned email notification:
- Customers will automatically receive an email notification
- The email shows their retroactive points and updated balance
If you didn't enable email notifications:
- Send an announcement email through your marketing channels
- Explain the loyalty program
- Show customers how to check their new balances
- Encourage them to redeem points
Common Questions
Q: Can I run retroactive points more than once?
A: No. Retroactive points is a one-time feature designed for initial setup. Once you run it or dismiss it, the feature is permanently hidden from the UI.
Q: What if I forgot to enable an earning rule?
A: You cannot include that earning rule in the retroactive job. Retroactive points only processes earning rules that are currently enabled. If you want to add more retroactive points later, you'll need to use Adjustments to manually award points.
Q: Can I cancel the job after starting it?
A: No. Once started, the retroactive points job cannot be cancelled. It will run to completion. Review your configuration carefully before starting.
Q: What happens to the CSV reports after 30 days?
A: The reports are automatically deleted after 30 days for data privacy and storage management. Download them promptly after they're generated.
Q: Will customers be notified about retroactive points?
A: Yes, if you enable the Retroactive points earned email notification in Email Notifications > Retroactive points earned. When enabled, customers automatically receive an email showing their retroactive points award and updated balance. If you don't enable this notification, you'll need to communicate the point awards through your own marketing channels.
Q: What if new customers sign up during retroactive processing?
A: Retroactive points processes data from the selected time period. New customers who join during processing are not included in the retroactive job but will earn points normally through active earning rules.
Q: Do retroactive points affect my existing earning rules?
A: No. Retroactive points is a separate one-time process. Your active earning rules continue to function normally for new actions.
Related Features
- Order Earning Rule - Current order points configuration
- Signup Earning Rule - Current signup points configuration
- Newsletter Earning Rule - Current newsletter points configuration
- Email Notifications - Configure retroactive points earned notifications
- Adjustments - Manual point modifications
- Imports - Bulk import customer data
- Customer Data - View customer point histories
Summary
Retroactive Points helps you:
Reward existing customers fairly when launching your loyalty program Award points for historical orders, signups, and newsletter subscriptions Generate detailed CSV reports of all point awards Maintain accurate transaction records with retroactive tagging Launch your loyalty program with existing customers already engaged
This one-time feature ensures no customer is left behind when you start your loyalty program!