> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/challenges-and-missions.md).

# Challenges & Missions

Building missions, milestones and streaks with challenges, showing members their progress, and the limits to design around.

A challenge is a goal made of milestones — "scan 3 different products", "buy 5 times this month", "check in every day this week". Progress comes from the transactions and custom events your integration already sends; milestone rules pay points, badges or spins along the way. Members usually see challenges as **missions**.

For the Admin Panel side, see [Creating challenges](https://help.openloyalty.io/campaigns/challenges/creating-challenges) and [Managing challenges](https://help.openloyalty.io/campaigns/challenges/managing-challenges). Events that feed challenges are covered in [Transactions](https://help.openloyalty.io/implementation-guide/module-checklists/transactions.md) and [Custom events](https://help.openloyalty.io/implementation-guide/module-checklists/custom-events.md).

## Who does what

| Area                           | Responsibility                                                                                                        |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | Challenges with milestones, rules, activity dates, completion limits and display attributes (images, per-day rewards) |
| **Integration layer**          | Sends the events that count — usually nothing extra; reads challenge lists and progress for the channels              |
| **Website / app**              | Mission cards (locked, in progress, completed), progress bars, check-in buttons                                       |
| **CRM / marketing automation** | Progress and completion messages from webhooks                                                                        |

## Design decisions

| Decision        | Options                                                                       | Recommendation                                                                                                                                            |
| --------------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What counts     | Number of events, or unique values of an attribute (product, flavour, colour) | Unique attributes for collection mechanics ("3 different flavours"); event counts for frequency ("5 purchases"). Make sure the attribute is in the event. |
| Period          | Overall, or reset weekly / monthly                                            | Use resetting periods for recurring missions instead of creating a new challenge each week. Decide before launch — see the warning below.                 |
| Rewards         | On completion only, or per milestone step                                     | A challenge has at most **6 milestones**, and a campaign at most **6 rules**. Group steps that pay the same into one rule.                                |
| Daily streaks   | A *streak* milestone, or a *counting* milestone with one event per day        | Counting milestone — see [Daily check-in streak](#daily-check-in-streak).                                                                                 |
| Display content | Hard-coded, or on the challenge                                               | Store images, per-step rewards and texts as challenge custom attributes, so the front end needs no release for a new mission.                             |
| Public missions | Only for members, or also logged-out visitors                                 | Label public missions (e.g. `public = true`) and list them with the campaigns list to invite visitors to join.                                            |

{% hint style="warning" %}
Don't change a milestone's goal type (for example *Overall* → *Weekly*) on a live challenge. The milestone gets a new ID; rules follow it, but members' existing progress stays on the old milestone and is lost.
{% endhint %}

## Recommended flow

{% stepper %}
{% step %}

### Design the mechanics

For each mission: what counts, the goal, the period, what each step pays, how often the whole challenge can be completed, and the activity dates. Check it fits in 6 milestones and 6 rules.
{% endstep %}

{% step %}

### Make sure the events carry the attributes

A milestone that counts unique flavours needs the flavour in every event. Add missing attributes to the custom event schema and the integration before configuring the challenge.
{% endstep %}

{% step %}

### Configure and test

Build the challenge on staging with display attributes, then drive it with test events: partial progress, completion, the completion limit, and the period reset.
{% endstep %}

{% step %}

### Show missions and progress

List the member's challenges with `GET /api/{storeCode}/member/{member}/campaign?trigger=challenge` (active challenges, display attributes, `limitReached`) and progress with `GET /api/{storeCode}/member/{member}/challenge` (per milestone `currentPeriodValue`, `periodGoal`, `completedCount`). For completed missions, use member history types `ChallengeCompleted` and `BadgeCompleted`.
{% endstep %}

{% step %}

### Correct or migrate progress

To carry over progress from a previous programme, or fix it for a member, use `PATCH /api/{storeCode}/member/{member}/challenge/{challenge}/progress`.
{% endstep %}
{% endstepper %}

## Sequence diagrams

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-f0578d36a3f6de3a1393ee401ca6edef4bf46ce9%2Fig-challenges-missions-page.png?alt=media" alt="A member opens the missions page. When logged in, the integration layer reads in parallel the member&#x27;s active challenges with display labels and limitReached, the progress per milestone, and the member&#x27;s badges, and returns mission cards as locked, in progress or completed. When logged out, it reads the public mission list by label and shows cards with a join prompt. Progress itself comes from events the member already sends." width="670"><figcaption><p>Missions page</p></figcaption></figure>

## Daily check-in streak

A "check in every day" mission is tempting to build on a *streak* milestone. In testing, **rules on a streak milestone don't fire on the intermediate days — only on completion**, so daily rewards aren't paid. Build it like this instead:

| Setting          | Value                                                                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Milestone        | Custom event `daily_check_in`, counting occurrences, goal *Weekly, at least N times*, event frequency limit **1 per day** (counted in the tenant's timezone) |
| Rules            | *Milestone progression = k* → add the day's reward; consecutive days with the same reward share one rule (`between`)                                         |
| Completion limit | 1 per calendar week                                                                                                                                          |
| Activity window  | Starts on a Monday, so the week and the streak line up                                                                                                       |
| Display          | Custom attributes `day1` … `dayN` with each day's reward                                                                                                     |

The "missed a day" check is done by the front end against the calendar: with `n` = days done this week and `dayIndex` = today's day of the week (Monday = 1), the streak is lost when `n < dayIndex − 1`.

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-5c7de8e24ef61525a87628904e6390ccceb7dcf4%2Fig-challenges-daily-checkin.png?alt=media" alt="The integration layer reads the member&#x27;s challenge progress n and computes dayIndex as the day of the week. If the limit is reached, the mission shows as completed this week; if n is less than dayIndex minus 1, the streak is lost and the mission is hidden until next week; if n equals dayIndex, today is done; if n equals dayIndex minus 1, the check-in button shows today&#x27;s reward. A check-in sends a daily_check_in custom event with the customer ID and date as eventId; the counting milestone moves on by one, the rule for that day pays the reward, and the last day completes the challenge." width="727"><figcaption><p>Daily check-in streak</p></figcaption></figure>

## Go-live checklist

### Admin Panel

* [ ] Every mission fits in 6 milestones and 6 rules.
* [ ] Periods, completion limits and activity dates are set as designed — no goal-type changes after launch.
* [ ] Display attributes (images, per-step rewards) are filled in for every challenge.

### Integration layer

* [ ] Every event a milestone counts carries the attributes it needs.
* [ ] Mission lists and progress are read from Open Loyalty, not computed by the front end.
* [ ] Check-in events use a per-member, per-day `eventId`.

### Website / app

* [ ] Cards show locked, in progress and completed states from `limitReached` and milestone progress.
* [ ] Daily streaks hide the mission once a day is missed.

### Validation

* [ ] Partial progress, completion and the completion limit behave as designed.
* [ ] A resetting period resets on the expected day.
* [ ] Each daily check-in pays that day's reward; a second check-in the same day doesn't.

## Key endpoints

* `GET /api/{storeCode}/member/{member}/challenge` — [Get member's challenge status](https://help.openloyalty.io/api-reference/campaign/get-members-challenge-status)
* `GET /api/{storeCode}/member/{member}/campaign` — [Get a list of available campaigns for the member](https://help.openloyalty.io/api-reference/campaign/get-a-list-of-available-campaigns-for-the-member) (with `trigger=challenge`)
* `PATCH /api/{storeCode}/member/{member}/challenge/{challenge}/progress` — [Update challenge progress for member](https://help.openloyalty.io/api-reference/campaign/update-challenge-progress-for-member)
* `GET /api/{storeCode}/member/{member}/badge` — [Return member badges status](https://help.openloyalty.io/api-reference/badge/return-member-badges-status)

**Webhooks:** [MemberChallengeProgressWasChanged](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/MemberChallengeProgressWasChanged), [ChallengesWereProcessed](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/ChallengesWereProcessed), [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied)

{% hint style="warning" %}
**Common pitfalls**

* Designing a mission with more steps or reward levels than 6 milestones and 6 rules allow.
* Counting unique flavours when the events don't send the flavour.
* Daily rewards on a streak milestone: nothing is paid until the streak completes.
* Changing a milestone's goal type on a live challenge and losing everyone's progress.
* Computing progress in the front end instead of reading it from Open Loyalty.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/challenges-and-missions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
