Skip to main content

​
Get Rewards

Authentication Required: Any authenticated user
GET /api/rewards
curl -X GET https://api.sunschool.xyz/api/rewards?learnerId=3 \
  -H "Authorization: Bearer {token}"
​
learnerId
number
Learner ID to get rewards for (shows progress for that learner)

​
Behavior by Role

  • LEARNER: Returns their parent’s reward catalog with their own savings progress
  • PARENT/ADMIN: Returns their own reward catalog (or filtered by learnerId)

​
Response

Response Example
[
  {
    "id": "reward_123",
    "parentId": 1,
    "title": "Extra Recess",
    "description": "15 minutes of extra free time",
    "tokenCost": 10,
    "category": "Time",
    "imageEmoji": "🏃",
    "color": "#4CAF50",
    "isActive": true,
    "maxRedemptions": null,
    "currentRedemptions": 0,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "savedPoints": 5
  }
]
​
savedPoints
number
Points saved toward this goal by the learner (only included when learnerId is provided)

​
Create Reward

Authentication Required: PARENT or ADMIN role
POST /api/rewards
curl -X POST https://api.sunschool.xyz/api/rewards \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Movie Night",
    "description": "Pick a movie for family night",
    "tokenCost": 25,
    "category": "Entertainment",
    "imageEmoji": "🎬",
    "color": "#2196F3"
  }'
​
title
string
required
Reward title
​
tokenCost
number
required
Cost in points to redeem this reward
​
description
string
Reward description
​
category
string
Reward category (e.g., “Time”, “Entertainment”, “Activities”)
​
maxRedemptions
number
Maximum number of times this reward can be redeemed (null for unlimited)
​
imageEmoji
string
Emoji to display for this reward
​
color
string
Hex color code for the reward card

​
Response

Returns the created reward object.

​
Error Codes

  • 400 - title and tokenCost are required
  • 401 - Unauthorized
  • 403 - Forbidden (not a parent/admin)

​
Update Reward

Authentication Required: PARENT or ADMIN role
PUT /api/rewards/:rewardId
curl -X PUT https://api.sunschool.xyz/api/rewards/reward_123 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenCost": 30,
    "isActive": true
  }'
​
rewardId
string
required
Reward ID to update
Accepts any of the fields from Create Reward, plus:
​
isActive
boolean
Whether the reward is active and available for redemption

​
Response

Returns the updated reward object.

​
Error Codes

  • 401 - Unauthorized
  • 403 - Forbidden (can only update your own rewards)
  • 404 - Reward not found

​
Delete Reward

Authentication Required: PARENT or ADMIN role
DELETE /api/rewards/:rewardId
curl -X DELETE https://api.sunschool.xyz/api/rewards/reward_123 \
  -H "Authorization: Bearer {token}"
​
rewardId
string
required
Reward ID to delete

​
Response

{
  "success": true
}

​
Error Codes

  • 401 - Unauthorized
  • 403 - Forbidden

​
Save Points Toward Goal

Authentication Required: Any authenticated user
POST /api/rewards/:rewardId/save
curl -X POST https://api.sunschool.xyz/api/rewards/reward_123/save \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "points": 5
  }'
​
rewardId
string
required
Reward ID to save points toward
​
points
number
required
Number of points to allocate to this goal (must be positive)
​
learnerId
number
Learner ID (for parent use)
This action deducts points from the learner’s balance and adds them to the savings goal for this specific reward.

​
Response

{
  "success": true,
  "pointsDelegated": 5
}

​
Error Codes

  • 400 - points must be positive
  • 401 - Unauthorized
  • 500 - Insufficient balance

​
Request Redemption

Authentication Required: Any authenticated user
POST /api/rewards/:rewardId/redeem
curl -X POST https://api.sunschool.xyz/api/rewards/reward_123/redeem \
  -H "Authorization: Bearer {token}"
​
rewardId
string
required
Reward ID to redeem
​
learnerId
number
Learner ID (for parent use)
The learner must have saved enough points toward this goal to cover the full cost. The redemption request will be pending until a parent approves it.

​
Response

Response Example
{
  "id": "redemption_456",
  "learnerId": 3,
  "rewardId": "reward_123",
  "pointsUsed": 10,
  "status": "PENDING",
  "requestedAt": "2024-01-15T10:30:00.000Z"
}

​
Error Codes

  • 400 - Insufficient points saved for this goal
  • 400 - Reward is not active
  • 400 - Max redemptions reached
  • 401 - Unauthorized

​
Get Redemptions (Parent)

Authentication Required: PARENT or ADMIN role
GET /api/redemptions
curl -X GET https://api.sunschool.xyz/api/redemptions?status=PENDING \
  -H "Authorization: Bearer {token}"
​
status
string
Filter by status: PENDING, APPROVED, or REJECTED
Returns redemption requests for the parent’s children.

​
Response

Response Example
[
  {
    "id": "redemption_456",
    "learnerId": 3,
    "learnerName": "Alice",
    "rewardId": "reward_123",
    "rewardTitle": "Extra Recess",
    "pointsUsed": 10,
    "status": "PENDING",
    "requestedAt": "2024-01-15T10:30:00.000Z"
  }
]

​
Get My Redemptions (Learner)

Authentication Required: Any authenticated user
GET /api/redemptions/my
curl -X GET https://api.sunschool.xyz/api/redemptions/my \
  -H "Authorization: Bearer {token}"
​
learnerId
number
Learner ID (for parent use)
Returns redemption requests for the authenticated learner (or specified learner if parent).

​
Approve Redemption

Authentication Required: PARENT or ADMIN role
PUT /api/redemptions/:redemptionId/approve
curl -X PUT https://api.sunschool.xyz/api/redemptions/redemption_456/approve \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Great job this week!"
  }'
​
redemptionId
string
required
Redemption ID to approve
​
notes
string
Optional notes for the learner

​
Response

Returns the updated redemption object with status “APPROVED”.

​
Reject Redemption

Authentication Required: PARENT or ADMIN role
PUT /api/redemptions/:redemptionId/reject
curl -X PUT https://api.sunschool.xyz/api/redemptions/redemption_456/reject \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": "Let's wait until after your homework is done."
  }'
​
redemptionId
string
required
Redemption ID to reject
​
notes
string
Optional notes for the learner
Rejecting a redemption returns the saved points back to the savings goal, so the learner can try again later.

​
Response

Returns the updated redemption object with status “REJECTED”.

​
Get Reward Summary

Authentication Required: Any authenticated user
GET /api/rewards-summary
curl -X GET https://api.sunschool.xyz/api/rewards-summary?learnerId=3 \
  -H "Authorization: Bearer {token}"
​
learnerId
number
Learner ID (defaults to authenticated user)
Returns a comprehensive summary of rewards, savings, and redemptions for a learner.

​
Response

Response Example
{
  "totalPointsSaved": 35,
  "availableBalance": 42,
  "goalsInProgress": 3,
  "totalRedeemed": 5,
  "pendingRedemptions": 1,
  "goals": [
    {
      "rewardId": "reward_123",
      "title": "Extra Recess",
      "tokenCost": 10,
      "savedPoints": 10,
      "progress": 100
    }
  ]
}