Skip to main content

​
Loyalty Rule Progress Tracking

External loyalty rules can be configured to track user progress and only allow completion when the progress reaches 100%. This feature enables you to create multi-step challenges or activities that users must complete incrementally.

​
Overview

When you enable progress tracking on an external loyalty rule:
  • Users can only claim the rule when their progress reaches 100%
  • You can define multiple reward tiers at different progress levels
  • Progress updates are submitted via the API
  • The claim button only appears when progress is 100%

​
Creating an External Rule with Progress Tracking

​
Step 1: Enable Progress Tracking

When creating an external loyalty rule, you need to enable the Track Progress option:
External rule creation form with Track Progress toggle
  1. Navigate to your loyalty rules section
  2. Create a new external rule
  3. Check the Track Progress checkbox
  4. Configure your rule settings as needed

​
Step 2: Configure Multiple Reward Tiers

With progress tracking enabled, you can define multiple reward ranges that trigger at different progress levels:
Reward configuration section showing progress ranges

​
Reward Options

For each progress range, you can configure:
  • Points: Award loyalty points at each milestone
  • Badges: Enable the “Reward badge per range” toggle to award badges along with points
When “Reward badge per range” is enabled, users will receive both points and badges at each progress milestone they reach.
Reward configuration section showing points and badge

​
Example Reward Configuration

You can set up reward ranges like this:
  • 10-10: 20 points + badge (awarded at 10% progress)
  • 20-20: 20 points + badge (awarded at 20% progress)
  • 50-90: 20 points + badge (awarded when progress is between 50-90%)
  • 100-100: 20 points + badge (awarded at 100% progress)
This means users can earn up to 4 separate rewards (points + badges) as they progress through the activity.

​
Updating User Progress

​
API Integration

To update a user’s progress, use the Update Loyalty Rule Status endpoint: Update Loyalty Rule Status API Documentation

​
Progress Values

  • Progress values should be integers between 0-100
  • When progress reaches 100%, the rule becomes claimable
  • Important: Updating progress does not automatically reward users
  • Users must go through the claim flow to receive rewards

​
User Experience

​
Progress Display

Users will see their current progress on the loyalty rule:
User-facing loyalty rule display showing progress bar and percentage

​
Multiple Reward Tiers

​
How Rewards Work

When you configure multiple progress ranges, users can earn rewards at different milestones:
  1. 10% Progress: First reward (20 points) - available for claim
  2. 20% Progress: Second reward (20 points) - available for claim
  3. 50-90% Range: Third reward (20 points) - available for claim when progress enters this range
  4. 100% Progress: Final reward (20 points) + rule completion - available for claim
Note: Progress updates only make rewards available for claiming. Users must actively claim their rewards through the verification flow to receive them.
After reward fulfillment (claim completion), the user’s progress data is preserved for 6 days.

​
Best Practices

  • Clear Milestones: Use round numbers (10, 25, 50, 75, 100) for better user understanding
  • Meaningful Rewards: Ensure each milestone provides value to encourage continued participation
  • Progress Feedback: Provide clear feedback when users reach new milestones
  • Range Planning: Consider user behavior when setting ranges (e.g., 50-90 allows for flexible completion)

​
Implementation Steps

  1. Create External Rule: Use the admin interface to create an external loyalty rule with progress tracking enabled
  2. Update Progress: Use the Update Loyalty Rule Status API to update user progress as they complete activities
  3. Enable Claiming: When progress reaches 100%, users can claim the rule through the verification flow

​
Troubleshooting

​
Common Issues

  1. Progress not updating: Ensure you’re using the correct loyaltyRuleId
  2. Rewards not triggering: Check that your progress ranges are correctly configured
  3. Claim button not appearing: Verify progress has reached exactly 100%

​
API Response

The update endpoint returns the current rule status: 
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "websiteId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "organizationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "loyaltyRuleId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "progress": 100,
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}
⌘I