# Mission

Missions are structured, multi-step engagement goals designed to guide users through sequential or grouped activities. By breaking campaigns into step-by-step milestone objectives within a specified aggregation period, missions turn repeat user actions into rewarding experiences.

:::tip
Link multiple milestones to a mission to build a step-by-step progress ladder. As users complete each milestone activity, rewards are automatically issued.
:::

## How it works

1. **Create a mission** — define a name, description, aggregation period (daily, weekly, monthly), and optional completion reward.
2. **Attach milestones** — link `Milestone` records to define specific progress thresholds or task steps.
3. **Log activity** — record user activities via `Mission Log` entries as actions take place.
4. **Track progress** — `Mission Progress` records automatically track progress, current state, and timestamps for each end user.
5. **Unlock rewards** — when milestones or total mission completion targets are met, a `Reward Log` entry is generated to deliver rewards to the user.

---

## Fields

### Basic information

| Field | Type | Required | Max length | Description |
|---|---|---|---|---|
| `name` | string | ✅ | 256 | The name of the mission |
| `description` | string | ✅ | 1 024 | A brief description of the mission |

### Aggregation settings

| Field | Type | Required | Default | Options | Description |
|---|---|---|---|---|---|
| `aggregationPeriod` | enum | ✅ | `daily` | `daily` · `weekly` · `monthly` | The time window over which user progress is measured and aggregated |

### Reward settings

| Field | Type | Required | Description |
|---|---|---|---|
| `rewardId` | UUID | ❌ | Optional ID of the reward to unlock automatically upon overall mission completion |

### Milestones

| Field | Type | Description |
|---|---|---|
| `milestones` | Milestone[] | List of milestone checkpoints attached to this mission |

---

## Real-world examples

**🛍️ E-commerce — Purchase & Review Mission**

A weekly mission prompting customers to make a purchase, leave a review, and share their order to earn a special reward.

```json
{
  "name": "Complete purchase cycle - Purchase, review and share",
  "description": "Complete the purchase cycle - Purchase, review and share and earn exclusive rewards.",
  "aggregationPeriod": "weekly",
  "rewardId": "123e4567-e89b-12d3-a456-426614174000"
}
```

---

**💄 Community Campaign — Daily Content & Engagement Mission**

A daily mission encouraging users to create and share user-generated content to unlock daily badges.

```json
{
  "name": "Complete your GRWM - Get ready with me to go out",
  "description": "Complete your GRWM - Get ready with me to go out and earn exclusive rewards.",
  "aggregationPeriod": "daily",
  "rewardId": "123e4567-e89b-12d3-a456-426614174001"
}
```

---

## 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 mission icon)* | — | Icon image. Allowed: PNG, JPEG, JPG, GIF, SVG · Max size: 100 KB |
| `eudInProgressLabel` | `In Progress` | 32 | Status label while mission is active |
| `eudCompletedLabel` | `Completed` | 32 | Status label when mission is finished |
| `eudNotStartedLabel` | `Not Started` | 32 | Status label before any activity |
| `eudFailedLabel` | `Failed` | 32 | Status label when mission time window expires without completion |
| `eudViewDetailsButtonText` | `View Details` | 32 | CTA button label |

### Messages

Messages support **template variables** that are resolved at runtime:

| Variable | Description | Example value |
|---|---|---|
| `{{$helpers.periodText}}` | Human-readable period derived from `aggregationPeriod` | `daily` → `day` · `weekly` → `week` · `monthly` → `month` |
| `{{$helpers.formattedMissionToBeFailedAt}}` | Expiration datetime when the mission will fail if uncompleted | `2026-08-31 23:59:59` |

| Field | Default | Max length |
|---|---|---|
| `eudCompletedMissionMessage` | `Congratulations! You have completed this mission! Come back next {{$helpers.periodText}} to shop more and start your next mission!` | 256 |
| `eudInProgressMissionMessage` | `Complete all milestones in this mission to earn rewards!` | 256 |
| `eudFailedMissionMessage` | `Your mission has been failed. Don\'t worry, you can start a new mission today! Shop more and reach your next milestone!` | 256 |
| `eudToBeFailedMissionMessage` | `Your mission will fail by {{$helpers.formattedMissionToBeFailedAt}} if you don\'t complete all the activities.` | 256 |

---

## Access & permissions

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

---

## Related resources

| Resource | Description |
|---|---|
| [Milestone](/milestone) | Step-by-step progress checkpoints linked to this mission |
| [Mission Log](/mission-log) | Activity logs recorded against the mission |
| [Mission Progress](/mission-progress) | Per-user progress state tracking for the mission |
| [Reward Log](/reward-log) | Rewards issued upon milestone or mission completion |
| [Reward](/reward) | Main reward unlocked upon completing the mission |

---

## API reference

See the [API Reference](/api/mission) for full request/response schemas and interactive examples for:

- `GET /schema/mission/record` — list missions
- `POST /schema/mission/record` — create a mission
- `GET /schema/mission/record/{id}` — get a mission by ID
- `PATCH /schema/mission/record/{id}` — update a mission
- `DELETE /schema/mission/record/{id}` — delete a mission