How Challenges Work

• Assignment: The customer receives the challenge (or self-enrolls from the app). The challenge defines one or more tracked milestones on the same progress metric.
• Progress tracking: The platform tracks challenge progress, updated at the frequency configured for the underlying customer attribute. The API endpoint customers/{value}/challenges returns the latest calculated status for progress bar rendering.
• Reward: When a milestone is reached, the prizes configured on that level of the challenge are delivered. A prize can be a discount, points, a reward/gift, or access to another game mechanic.

How It Works

1. Assignment — the challenge is made available to qualifying customers (automatically or via enrollment).
2. Tracking — each purchase or custom event updates the customer attribute that the challenge monitors.
3. Progress API — your app calls GET /customers/{customer_id}/challenges to render progress bars with the latest calculated values.
4. Win detection — the platform compares the attribute value to each level threshold. On a progressive challenge, progress is cumulative: reaching level 3 implies levels 1 and 2 were already crossed. If one recalculation jumps several thresholds, every crossed level is won in that run.
5. Prize delivery — for each newly won level, the prizes selected on the challenge for that level are delivered: discount, points, reward/gift (catalog + targeted only; added to the customer's personalized catalog for later redeem — never auto-redeemed on win), or access to another game mechanic.

note

Challenges track one progress metric. Use Single milestone for one threshold and its prizes, or Progressive for 2–5 increasing thresholds on the same metric with prizes per level. Multi-action challenges (different actions in one challenge) are not available yet.

Enrollment Mechanics

When a challenge requires enrollment, the following rules apply:

• Only customers who have explicitly subscribed (enrolled) can win — reaching the goal without enrolling does not grant the prize.
• Customers can enroll before the challenge start date but never after the end date.
• Customers from countries not defined on the challenge cannot participate, even if they know the challenge exists.

Progress is not gated by the enrollment date. The challenge reads the selected Calculated Attribute as-is. Whether carts or events before enrollment (or before the challenge start date) count toward progress depends entirely on how that progression metric is defined — its period, filters, and calculation logic. By default, enrollment does not cut off or start the metric; if you need activity before enrollment (or before start) excluded, configure the Calculated Attribute accordingly.

tip

Customers who enroll early may already show progress when the challenge starts, if the attribute window includes earlier activity. That is expected when the metric is configured that way — not a platform bug.

Targeted Delivery and Recurrence Dates

Challenges can be promoted or assigned through Targeted Delivery, including recurrent sends. In that setup, four date layers can interact:

Layer	Controls
Display dates	Whether the Challenge can appear in the customer's app catalogue.
Availability dates	Whether the Challenge is active and can be won.
Expiration policy	When a won Challenge resets and can be attempted again.
Targeted Delivery recurrence	When the Audience receives the Challenge communication or assignment.

The Challenge must remain active for the whole period covered by the recurrence. A weekly recurrent delivery does not make the Challenge weekly by itself: the Challenge availability, the underlying customer attribute period, and the expiration policy must all support the intended weekly behavior.

For example, if a Challenge is sent every Monday for four weeks, configure the Challenge so it is visible and available across those four weeks. If Customers should be able to win once per week, align the calculated attribute period and expiration policy with that weekly reset. If the Challenge availability ends after week one, later sends may still run but the Challenge will not be available to win.

Example: 6-month Challenge with monthly Targeted Delivery

You want customers to participate from January through June, and a Targeted Delivery that assigns or reminds them once a month for those six months.

What you configure	Example
Challenge availability	1 Jan – 30 Jun (full six months)
Challenge display	Same dates, or open slightly earlier if the Challenge should appear before the first send
Targeted Delivery recurrence	Monthly, six sends (e.g. 1st of each month, Jan–Jun)
Calculated Attribute period	Once-per-month goal: current_month (or equivalent). One continuous 6-month goal: a period that covers the whole participation window.
Expiration policy	Once-per-month wins: at the end of the calculation window (so the Challenge resets each month). Single win in six months: months/days after winning, or simply let availability end the Challenge.

The monthly Targeted Delivery only controls when the Audience is notified or assigned. It does not extend Challenge availability or reset progress. If availability stopped in January, later monthly sends would still fire, but customers could not win outside that window.

Configuration

Challenge setup happens in one Owner App flow — including prizes:

Step	Owner App path
Create the challenge (format, Select a Customer, levels, and prizes)	Gamified Campaigns → Challenges → New Challenge

Select a Customer: choose Loyalty Club (available to club members) or Targeted (only customers assigned via Targeted Delivery can see and participate). See Create a Challenge.

See Create a Challenge for the full step-by-step guide and Prizes for prize types and selection rules.

tip

In the customer profile, Active Challenges is an expandable table: one row per challenge, with nested rows for each level (threshold, reached, won date).

API Reference

The Streaming API exposes four endpoints for challenge integration:

Method	Endpoint	Description
GET	/customers/{customer_id}/challenges	Returns the full challenge catalogue for a customer, including current progress and enrollment status. Enrolled challenges appear first. Only active challenges within availability dates and matching the customer's country are returned.
GET	/challenges	Returns all challenges available, filtered by country.
GET	/challenges/{id}	Returns a specific challenge by ID.
POST	/challenges/{id}/enroll	Enrolls a customer in a challenge. Validates: enrollment is allowed, challenge is within dates, customer is from an eligible country, enrollment cap has not been reached, customer is not already enrolled.

Building a Progress Bar

Progress bars are a highly recommended UI element — they give customers visibility of their progress and motivate completion. Use the /customers/{customer_id}/challenges endpoint to retrieve the data needed to render them.

Key Response Fields

For each challenge in the catalogue, the endpoint returns:

Field	Description
attribute_value	The last calculated value of the customer attribute. This is the customer's current progress toward the next (or only) threshold. Updated at the frequency defined for the attribute — not in real time.
attribute_name	Display name of the Calculated Attribute used as the progress metric.
current_level	The customer's current level position on the challenge ladder.
to_reach_next_level_value	The remaining value the customer needs to reach the next level (next threshold minus current value).
structure	Array of levels. Each level includes level, name, threshold, reached, optional won_at, and the prizes for that level.
structure[].threshold	The goal for that level.
structure[].reached	true if attribute_value >= that level's threshold; false otherwise.
structure[].won_at	The datetime when that level was won. Only present when reached = true.
last_execution_time	When the attribute_value was last recalculated.

Example: If the next threshold is 100 and attribute_value = 70, then to_reach_next_level_value = 30. Render the progress bar at 70% toward the next level. On a progressive challenge, also show completed levels from structure[].

Award in the Response

Each challenge response includes an awards array for backward-compatible prize display. Richer prize detail (including discount coupons and mixed prize types per level) is available via prizes on each level in structure[] and/or at challenge level, depending on the integration contract.

Field	Description
awards[].type	Prize type returned by the API, such as "score" for points prizes or "reward" for reward/gift prizes.
awards[].amount	Points the customer wins. Only present when type = "score".
awards[].reward_id	ID of the reward to be granted. Only present when type = "reward".
awards[].reward_name	Display name of the reward (localized per Accept-Language header if multilanguage is enabled). Only present when type = "reward".
awards[].loyalty_score_id	ID of the loyalty rule that generates this award.
Level prizes[]	Per-level prize objects (e.g. points, discount coupon, reward, game) for app rendering — use these when you need full prize detail beyond awards.

tip

It is strongly recommended to implement progress bars in the customer app. Customers who can see their progress toward a goal convert at higher rates and complete more challenges.