Skip to content

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
FieldTypeRequiredDescription
headerOnlybooleanNOfalse by default. true asks for the summary only (used by the levels screen).
sessionIdstringYESInjected.
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 ​

FieldMeaning
trackIDReward track id (used as trackId when opting in).
trackName / trackDescriptionShown in the opt-in dialog.
userOptInStatus1 = opted in, 0 = not opted in. If 0, the app blocks the tab with an opt-in dialog.
userLevelPatron's current level.
userExperiencePointsPoints earned toward the next level.
userCurrentPointsSpendable points in the store.
hasLevelsShow the Levels tab.
hasRedeemableRewardsShow the Store tab.
trackLevelsLevel definitions plus the rewards unlocked at each level.
redeemableRewardsRewards that can be bought with points (the store).

Level fields ​

FieldMeaning
levelLevel number (1-based).
requiredPointsExperience points required to reach this level.
userClaimableRewardsRewards attached to this level.

Reward fields ​

FieldMeaning
idReward id.
shortDescription / descriptionDisplay strings.
claimStatus0 unearned, 1 earned, 2 claimed, 3 received.
claimLevelLevel required to claim the reward.
rewardLevelLevel the reward belongs to.
pointCostStore price in points.
pointsSpentPoints already spent (history items).
receivedTimeWhen the reward was consumed (history).

The app derives a level status that is separate from the raw claim status:

ValueDerivation
0 lockeduserLevel < level
1 unlockedLevel reached, nothing claimed yet
2 claimedA reward on this level has claimStatus = 2
3 receivedA 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
FieldTypeRequiredDescription
rewardTrackIdstring | nullNOTrack to filter by. The app sends null.
startDatestring | nullNOISO date. The app sends null.
endDatestring | nullNOISO date. The app sends null.
filtersobject | nullNOThe app sends null.
sessionIdstringYESInjected.
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
}
FieldMeaning
idLedger entry id.
rewardIdReward this entry refers to.
status0 unearned, 1 earned, 2 claimed, 3 received.
receivedTimeWhen 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
FieldTypeRequiredDescription
trackIdstringYEStrackID from the track info.
userIdstringYESCurrent user id.
sessionIdstringYESInjected.
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
FieldTypeRequiredDescription
rewardIdstringYESReward id.
sessionIdstringYESInjected.
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 statusUI
2 claimedShows a QR code for the cashier to scan.
anything elseShows 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:

TabShown whenDefault active
LevelshasLevels = trueyes, if present
StorehasRedeemableRewards = trueyes if Levels is absent
Historyalwaysno

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:

ConditionMessage
Any request failuresomething went wrong, try again later (toast)
RewardsDisabledForUserExceptionUse of GET Rewards has been disabled for this user.

See Reference for the full exception list.