Challenge Progress Bar
Use this guide when an app needs to display challenge progress for a customer, such as "buy 5 times this month" or "spend EUR100 before Sunday".
Core endpoints
| Endpoint | Use it for |
|---|---|
GET /challenges | List active challenge campaigns. |
GET /challenges/{id} | Read challenge configuration. |
POST /challenges/{id}/enroll | Enroll the customer when the challenge requires opt-in. |
GET /customers/{value}/challenges | Read all challenge progress for a customer. |
GET /customers/{value}/challenges/{id} | Read progress for one challenge. |
Rendering flow
Progress calculation for UI
Render the progress bar from the API values:
progress_percent = min(current_value / target_value * 100, 100)
Always handle these states:
| State | UI behavior |
|---|---|
| Not enrolled | Show opt-in CTA if the challenge requires enrollment. |
| In progress | Show current value, target value, and remaining amount. |
| Completed | Show completed state and reward/voucher messaging if applicable. |
| Expired | Hide action CTA or show expired state. |
| Not available | Do not show the challenge if it is outside availability or not visible to the customer. |
Challenge dates and targeted delivery
Challenges can combine several date concepts:
- Availability dates: when the challenge can be visible/playable/enrollable.
- Expiration date: when progress can no longer complete.
- Targeted delivery send dates: when the campaign communication or voucher assignment is sent to customers.
- Recurrence: targeted deliveries can be sent repeatedly, but the challenge must still be active for the whole period where customers are expected to progress.
If a challenge is promoted through recurring targeted deliveries, keep the challenge active for the full recurrence period, not only for the send day.
Freshness and recalculation
Challenge progress may depend on calculated attributes or cart events. If a customer just made a purchase and the progress did not update immediately, check the configured recalculation frequency and whether the relevant cart/custom event has been processed.
Troubleshooting
| Symptom | What to check |
|---|---|
| Progress stays at zero | Customer ID, challenge enrollment, calculated attribute freshness, event ingestion, and whether the challenge condition matches the cart data. |
| Progress reaches target but no voucher appears | Challenge completion action, targeted delivery/voucher generation, reward configuration, and customer voucher list. |
| Challenge appears after it should end | Availability, expiration, recurrence, and app-side cache. |
| App shows a challenge the customer cannot join | Audience, enrollment requirement, customer status, and challenge visibility conditions. |