Appearance
Rewards
Service path: /json/rewards
GET Rewards is an optional module. When an institution has it enabled the patron app shows a Rewards tab with up to three sub-tabs: Levels, Store, and History. The server decides which tabs exist by returning hasLevels and hasRedeemableRewards.
NOTE
Every rewards method is flagged useSessionId = true and useInstitutionId = false, so only sessionId is injected.
Reward track info
Returns the patron's reward track: their level, points, the levels in the track, and the rewards they can claim.
plaintext
POST /json/rewards
method: retrieveUserRewardTrackInfo| Field | Type | Required | Description |
|---|---|---|---|
headerOnly | boolean | NO | false by default. true asks for the summary only (used by the levels screen). |
sessionId | string | YES | Injected. |
json
{
"method": "retrieveUserRewardTrackInfo",
"params": {
"headerOnly": false,
"sessionId": "{SESSION_ID}"
}
}The response is an array; the app uses the first element and treats an empty array as "no rewards". Null is also handled.
json
{
"response": [
{
"trackID": "{TRACK_ID}",
"trackName": "Dining Rewards",
"trackDescription": "Earn points every time you eat on campus.",
"userOptInStatus": 1,
"userLevel": 2,
"userExperiencePoints": 340,
"userCurrentPoints": 120,
"hasLevels": true,
"hasRedeemableRewards": true,
"trackLevels": [
{
"level": 1,
"requiredPoints": 0,
"userClaimableRewards": []
},
{
"level": 2,
"requiredPoints": 250,
"userClaimableRewards": [
{
"id": "{REWARD_ID}",
"shortDescription": "Free coffee",
"description": "One free medium coffee",
"claimStatus": 1,
"claimLevel": 2,
"rewardLevel": 2,
"receivedTime": null
}
]
}
],
"redeemableRewards": [
{
"id": "{REWARD_ID}",
"shortDescription": "Free coffee",
"description": "One free medium coffee",
"pointCost": 100,
"claimStatus": 1
}
]
}
],
"exception": null
}Track fields
| Field | Meaning |
|---|---|
trackID | Reward track id (used as trackId when opting in). |
trackName / trackDescription | Shown in the opt-in dialog. |
userOptInStatus | 1 = opted in, 0 = not opted in. If 0, the app blocks the tab with an opt-in dialog. |
userLevel | Patron's current level. |
userExperiencePoints | Points earned toward the next level. |
userCurrentPoints | Spendable points in the store. |
hasLevels | Show the Levels tab. |
hasRedeemableRewards | Show the Store tab. |
trackLevels | Level definitions plus the rewards unlocked at each level. |
redeemableRewards | Rewards that can be bought with points (the store). |
Level fields
| Field | Meaning |
|---|---|
level | Level number (1-based). |
requiredPoints | Experience points required to reach this level. |
userClaimableRewards | Rewards attached to this level. |
Reward fields
| Field | Meaning |
|---|---|
id | Reward id. |
shortDescription / description | Display strings. |
claimStatus | 0 unearned, 1 earned, 2 claimed, 3 received. |
claimLevel | Level required to claim the reward. |
rewardLevel | Level the reward belongs to. |
pointCost | Store price in points. |
pointsSpent | Points already spent (history items). |
receivedTime | When the reward was consumed (history). |
The app derives a level status that is separate from the raw claim status:
| Value | Derivation |
|---|---|
0 locked | userLevel < level |
1 unlocked | Level reached, nothing claimed yet |
2 claimed | A reward on this level has claimStatus = 2 |
3 received | A reward on this level has claimStatus = 3 |
Reward history
Returns the patron's reward ledger. Used for the History tab and to decorate store and level rewards with their latest status.
plaintext
POST /json/rewards
method: retrieveUserRewardHistory| Field | Type | Required | Description |
|---|---|---|---|
rewardTrackId | string | null | NO | Track to filter by. The app sends null. |
startDate | string | null | NO | ISO date. The app sends null. |
endDate | string | null | NO | ISO date. The app sends null. |
filters | object | null | NO | The app sends null. |
sessionId | string | YES | Injected. |
json
{
"method": "retrieveUserRewardHistory",
"params": {
"rewardTrackId": null,
"startDate": null,
"endDate": null,
"filters": null,
"sessionId": "{SESSION_ID}"
}
}Response is an array of history entries:
json
{
"response": [
{
"id": "{HISTORY_ID}",
"rewardId": "{REWARD_ID}",
"status": 3,
"receivedTime": "2026-11-01T12:34:56"
}
],
"exception": null
}| Field | Meaning |
|---|---|
id | Ledger entry id. |
rewardId | Reward this entry refers to. |
status | 0 unearned, 1 earned, 2 claimed, 3 received. |
receivedTime | When it was received. |
The history tab shows only entries whose status is 3 (received).
Opt into a reward track
Required before any rewards data is shown when
userOptInStatus = 0.
plaintext
POST /json/rewards
method: optUserIntoRewardTrack| Field | Type | Required | Description |
|---|---|---|---|
trackId | string | YES | trackID from the track info. |
userId | string | YES | Current user id. |
sessionId | string | YES | Injected. |
json
{
"method": "optUserIntoRewardTrack",
"params": {
"trackId": "{TRACK_ID}",
"userId": "{USER_ID}",
"sessionId": "{SESSION_ID}"
}
}The response is a boolean. The app treats a truthy value as success and shows the opt-in confirmation toast.
Claim / redeem a reward
plaintext
POST /json/rewards
method: claimRewardV2| Field | Type | Required | Description |
|---|---|---|---|
rewardId | string | YES | Reward id. |
sessionId | string | YES | Injected. |
json
{
"method": "claimRewardV2",
"params": {
"rewardId": "{REWARD_ID}",
"sessionId": "{SESSION_ID}"
}
}The response is the updated reward object:
json
{
"response": {
"id": "{REWARD_ID}",
"status": 2,
"shortDescription": "Free coffee",
"description": "One free medium coffee"
},
"exception": null
}After a claim the app checks status:
| Resulting status | UI |
|---|---|
2 claimed | Shows a QR code for the cashier to scan. |
| anything else | Shows the success dialog. |
The app then reloads the track and history so the reward moves from "available" to "ready to scan".
IMPORTANT
claimRewardV2 is the only claim method the 5.1.20 build calls. There is no claimReward (v1) call site.
Tab construction
The client builds the tab bar from the track response, not from a server field:
| Tab | Shown when | Default active |
|---|---|---|
| Levels | hasLevels = true | yes, if present |
| Store | hasRedeemableRewards = true | yes if Levels is absent |
| History | always | no |
Tab labels come from content strings in patron-ui.rewards (level_tab_title, store_tab_title, history_tab_title), falling back to Levels / Store / History.
Errors
Rewards errors use the standard exception envelope. The client also handles:
| Condition | Message |
|---|---|
| Any request failure | something went wrong, try again later (toast) |
RewardsDisabledForUserException | Use of GET Rewards has been disabled for this user. |
See Reference for the full exception list.