# Reward Log

Reward Logs are **automatically created by the platform** whenever an end user reaches a milestone's `milestoneTargetValue`. Each log contains the coupon code for that reward and timestamps tracking its full lifecycle — from issuance through redemption or expiry.

:::info
Reward Logs are never created manually. They are generated by the platform's whenever a milestone is achieved in streak or challenge.
:::

## How it works

1. **Milestone threshold crossed** — an end user's progress on a streak or challenge reaches a milestone's `milestoneTargetValue`.
2. **Reward Log created** — the platform automatically creates a Reward Log entry when a user achieves a milestone which can be updated by you with `couponCode`, `rewardIssuedAt` and `rewardExpiryAt` for display purposes to their users
3. **End user sees the reward** — the reward is surfaced in the end-user widget with the coupon code and redemption instructions from the parent milestone's `eudMilestoneRewardInstructionMessage`.
5. **Reward expires** — if `rewardExpiryAt` is set and the coupon has not been redeemed by that time, the reward is shown expired to the user on the dashboard.

---

## Fields

| Field | Type | Required | Notes |
|---|---|---|---|
| `linkedSchemaSlug` | string | ✅ | Slug of the parent schema — `streak` or `challenge`. Set by the system; max 32 chars. |
| `linkedSchemaRecordId` | UUID | ✅ | ID of the specific streak or challenge record. Non-editable after creation. |
| `milestoneId` | UUID | ✅ | ID of the milestone that triggered this reward. Non-editable after creation. |
| `milestone` | object | — | Read-only joined milestone object. |
| `couponCode` | string | ❌ | The coupon code issued to the end user. It is null when a milestone is achieved and should be updated by you with the coupon code unlocked for the user |
| `rewardIssuedAt` | datetime | ❌ | Timestamp when the reward was issued to the user |
| `rewardExpiryAt` | datetime | ❌ | Timestamp when the reward expires. |
| `periodKey` | string | - | The time-period key for the reward. Mirrors the parent streak/challenge period — e.g., `monthly_2026-04` for monthly, `weekly_2026-15` for weekly, `daily_2026-04-10` for daily. Max 16 chars. Non-editable. |
| `uniqueIdentifier` | string | - | Auto-generated composite key: `linkedSchemaSlug + linkedSchemaRecordId + ownedById + periodKey`. Ensures one reward per user per milestone per period. Max 256 chars. Non-editable |

---

## Lifecycle states

A Reward Log moves through the following states based on its timestamps:

| State | Condition |
|---|---|
| **Issued** | `rewardIssuedAt` is set; `rewardExpiryAt` are null or in the future |
| **Expired** | `rewardExpiryAt` is in the past |

---

## Real-world examples

**🛍️ E-commerce — 3-day streak milestone reward**

A user completes 3 consecutive days of spending and achieves a milestone. The Reward Log is created by the system automatically:

```json
{
  "linkedSchemaSlug": "streak",
  "linkedSchemaRecordId": "a1b2c3d4-0000-0000-0000-000000000000",
  "milestoneId": "m1m2m3m4-0000-0000-0000-000000000000",
  "periodKey": "2026-04-08",
  "ownedById": "user-uuid-here"
}
```

After the coupon code is issued by you on milestone achievement, update the reward log

```json
PATCH /schema/reward_log/record/{id}
{
  "rewardIssuedAt": "2026-04-09T10:05:00Z",
  "couponCode": "coupon-code-here",
  "rewardExpiryAt": "2026-05-09T10:05:00Z"
}
```


## Access & permissions

| Caller | Allowed operations | Notes |
|---|---|---|
| Admin | GET · LIST · UPDATE | No CREATE or DELETE — logs are system-generated only |
| End user | GET · LIST | Can read their own reward logs; cannot write |
| Guest user | *(none)* | Not accessible to unauthenticated callers |

:::warning
Reward Logs **cannot be created or deleted** via the API. Attempting a `POST` or `DELETE` will return `405 Method Not Allowed`. They are created exclusively by the platform when a milestone threshold is crossed.
:::

---

## Related resources

| Resource | Description |
|---|---|
| [Milestone](/milestone) | Parent milestone that defines the target value and coupon for this reward |
| [Streak](/streak) | Parent streak whose progress can trigger milestone rewards |
| [Challenge](/challenge) | Parent challenge whose progress can trigger milestone rewards |

---

## API reference

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

- `GET /schema/reward_log/record` — list reward logs
- `GET /schema/reward_log/record/{id}` — get a reward log by ID
- `PATCH /schema/reward_log/record/{id}` — update a reward log