Copy page

Getting Started

Challenges

Challenges are time-bound engagement goals that reward users for hitting a cumulative completionTargetValue within a defined aggregation period. Unlike streaks, challenges measure total progress toward a single target — not consecutive periods — making them ideal for sprint-style campaigns.

How streaks vs challenges differ

	Streak	Challenge
Goal	Complete N consecutive periods	Accumulate progress toward a total target
Fails when	A period is missed	The challenge window ends before the target is met
Status when missed	broken	failed
Reset	Starts fresh next period	Starts fresh next challenge window

---

How it works

1. Create a challenge — define a name, aggregation method, aggregation period, and a completionTargetValue (the total activity needed to win).
2. Attach milestones — link Milestone records to the challenge for intermediate reward checkpoints.
3. Log activity — send Challenge Log entries as users perform qualifying actions. The platform aggregates them automatically.
4. Track progress — Challenge Progress records are maintained per user, tracking currentProgressValue, status, and timestamps.
5. Earn rewards — when a milestone threshold or completionTargetValue is crossed, a Reward Log entry is created with a coupon code.

---

Fields

Basic information

Field	Type	Required	Max length	Description
name	string	✅	256	The name of the challenge
description	string	✅	1 024	A brief description of the challenge
status	enum	✅	—	draft · live · paused
completionTargetValue	number	✅	—	The total cumulative value a user must reach to complete the challenge

Aggregation settings

Aggregation controls how the platform measures cumulative progress from incoming Challenge Log entries.

Field	Type	Required	Default	Options	Description
aggregationMethod	enum	✅	sum	sum · count	How log values are combined — sum adds activityValue, count counts the number of log entries
aggregationPeriod	enum	✅	daily	daily · weekly · monthly	The time window that defines the challenge duration

Example: a challenge with aggregationMethod: sum, aggregationPeriod: monthly, and completionTargetValue: 500 requires the user to accumulate $500 of spend within the current month to complete the challenge.

Real-world examples

🛍️ E-commerce — "Monthly Big Spender" challenge

Win a reward by spending $500 in a single month. Milestone at $200 gives 5% off; completing $500 gives free shipping for 3 months.

Code
{
  "name": "Monthly Big Spender",
  "description": "Spend $500 this month to unlock exclusive rewards.",
  "status": "live",
  "aggregationMethod": "sum",
  "aggregationPeriod": "monthly",
  "completionTargetValue": 500
}

---

☕ Food & Beverage — "10 Visits This Month" challenge

Visit 10 times in a month to earn a free item. Milestone at 5 visits gives a discount.

Code
{
  "name": "10 Visits This Month",
  "description": "Visit us 10 times this month and earn a free item.",
  "status": "live",
  "aggregationMethod": "count",
  "aggregationPeriod": "monthly",
  "completionTargetValue": 10
}

aggregationMethod: count — each Challenge Log entry counts as 1 visit regardless of activityValue.

---

🏋️ Fitness — "Weekly Burn 5 000 Calories" challenge

Log 5 000 calories burned in a single week to win a gym merchandise voucher.

Code
{
  "name": "Weekly Burn 5K",
  "description": "Burn 5,000 calories this week and earn a reward.",
  "status": "live",
  "aggregationMethod": "sum",
  "aggregationPeriod": "weekly",
  "completionTargetValue": 5000
}

---

📚 EdTech — "Complete 20 Lessons This Month" challenge

Finish 20 lessons in a month to unlock a premium content pack.

Code
{
  "name": "20 Lessons Challenge",
  "description": "Complete 20 lessons this month to unlock premium content.",
  "status": "live",
  "aggregationMethod": "count",
  "aggregationPeriod": "monthly",
  "completionTargetValue": 20
}

Milestones

Field	Type	Description
milestones	Milestone[]	Read-only. Milestones linked to this challenge. Manage them from the Milestones tab.

---

End-user display (EUD)

All EUD fields are localisable — supply a languageCode query parameter when reading to receive the translated value.

Labels

Field	Default	Max length	Description
eudTitle	—	48	Title shown to the end user
eudDescription	—	1 024	Description shown to the end user
eudIcon	(default challenge icon)	—	Icon image. Allowed: PNG, JPEG, JPG, GIF, SVG · Max size: 100 KB
eudInProgressLabel	In Progress	32	Status label while challenge is active
eudCompletedLabel	Completed	32	Status label when challenge is won
eudNotStartedLabel	Not Started	32	Status label before any activity
eudFailedLabel	Failed	32	Status label when the challenge window closes without completion
eudViewDetailsButtonText	View Details	32	CTA button label

Messages

Messages support template variables resolved at runtime:

Variable	Description	Example value
{{periodText}}	Human-readable period name from aggregationPeriod	daily → day · weekly → week · monthly → month
{{nextRemainingValue}}	Amount still needed to reach the next milestone	150.00 (user has $350, next milestone at $500 → $150 remaining)

Field	Default	Max length
eudCompletedChallengeMessage	Congratulations! You have completed this challenge! Shop more next {{periodText}} to start a new challenge!	256
eudFailedChallengeMessage	Your challenge has failed. Don't worry, shop more next {{periodText}} to start a new challenge!	256
eudMilestoneNextToBeAchievedMessage	Shop for ${{nextRemainingValue}} or more to complete the next milestone!	256

Rendered examples — for a monthly spend challenge where the user spent $350 and the next milestone is at $500:

Variable	Resolved value
{{periodText}}	month
{{nextRemainingValue}}	150.00

Shop for $150.00 or more to complete the next milestone!

On completion:

Congratulations! You have completed this challenge! Shop more next month to start a new challenge!

On failure:

Your challenge has failed. Don't worry, shop more next month to start a new challenge!

---

Access & permissions

Caller	Allowed operations
Admin	CREATE · GET · LIST · UPDATE · DELETE
End user	GET · LIST
Guest (unauthenticated)	GET · LIST

---

Related resources

Resource	Description
Milestone	Reward checkpoints attached to a challenge
Challenge Log	Individual activity events logged against a challenge
Challenge Progress	Per-user progress state for a challenge
Reward Log	Rewards issued when a milestone or completion threshold is reached

---

API reference

See the API Reference for full request/response schemas and interactive examples for:

• GET /schema/challenge/record — list challenges
• POST /schema/challenge/record — create a challenge
• GET /schema/challenge/record/{id} — get a challenge by ID
• PATCH /schema/challenge/record/{id} — update a challenge
• DELETE /schema/challenge/record/{id} — delete a challenge