Skip to main content

​
Get Points Balance

Authentication Required: Any authenticated user
GET /api/points/balance
curl -X GET https://api.sunschool.xyz/api/points/balance?learnerId=3 \
  -H "Authorization: Bearer {token}"
​
learnerId
string
Learner ID to get balance for (required for PARENT/ADMIN, defaults to authenticated user for LEARNER)

​
Authorization

  • LEARNER: Can only access their own balance
  • PARENT: Can access their children’s balances with learnerId param
  • ADMIN: Can access any learner’s balance

​
Response

Response Example
{
  "balance": 42
}

​
Error Codes

  • 400 - learnerId required
  • 403 - Forbidden

​
Get Points History

Authentication Required: Any authenticated user
GET /api/points/history
curl -X GET https://api.sunschool.xyz/api/points/history?learnerId=3&limit=20 \
  -H "Authorization: Bearer {token}"
​
learnerId
string
Learner ID to get history for (required for PARENT/ADMIN, defaults to authenticated user for LEARNER)
​
limit
number
Maximum number of transactions to return (default: 50)

​
Authorization

Same as Get Points Balance.

​
Response

​
transactions
array
Array of point transaction records
Response Example
[
  {
    "id": "txn_123456",
    "learnerId": 3,
    "amount": 5,
    "sourceType": "QUIZ_CORRECT",
    "sourceId": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Quiz 75% [Double-or-Loss]",
    "balanceAfter": 42,
    "createdAt": "2024-01-15T10:30:00.000Z"
  },
  {
    "id": "txn_123455",
    "learnerId": 3,
    "amount": -10,
    "sourceType": "REWARD_SAVE",
    "sourceId": "reward_789",
    "description": "Saved for Extra Recess",
    "balanceAfter": 37,
    "createdAt": "2024-01-15T09:15:00.000Z"
  }
]

​
Error Codes

  • 400 - learnerId required
  • 403 - Forbidden

​
Get Current Balance (Simplified)

Authentication Required: Any authenticated user
GET /api/points
curl -X GET https://api.sunschool.xyz/api/points \
  -H "Authorization: Bearer {token}"
Returns the points balance for the authenticated user.

​
Response

{
  "balance": 42
}

​
Error Codes

  • 401 - Unauthorized

​
Points Source Types

Common source types in the points system:
  • QUIZ_CORRECT - Points earned from correct quiz answers
  • REWARD_SAVE - Points delegated to a reward savings goal
  • REWARD_REDEMPTION - Points used to redeem a reward
  • DOUBLE_OR_LOSS_DEDUCTION - Points deducted from wrong answers in double-or-loss mode
  • ADMIN_ADJUSTMENT - Manual adjustment by an administrator
All point transactions are immutable and stored with a complete audit trail including timestamps, source information, and running balance.