Rewards API

List available rewards, claim them, and query claimed history. Rewards can optionally deduct points as a cost.

Authentication: All endpoints require an X-API-Key header. Base URL: https://YOUR_API_DOMAIN/api/v1/gamify

Method	Endpoint	Description
GET	`/gamify/rewards`	List available rewards. Filter by `?reward_type=coupon`.
POST	`/gamify/rewards/{reward_id}/claim`	Claim a reward. Optionally deduct points.
GET	`/gamify/participants/{pid}/rewards`	List all rewards claimed by participant.

List Available Rewards

GET /api/v1/gamify/rewards?reward_type=coupon

{
  "rewards": [
    {
      "id": "rwd_uuid",
      "name": "10% Off Coupon",
      "type": "coupon",
      "description": "10% discount on next purchase",
      "points_cost": 500,
      "available_codes": 45,
      "max_claims_per_user": 1
    }
  ],
  "total": 1
}

Claim a Reward

Set points_deduction: true to automatically deduct the reward's points cost from the participant's balance.

POST /api/v1/gamify/rewards/rwd_uuid/claim

{
  "participant_id": "user_123",
  "points_deduction": true
}

// Response
{
  "claim_id": "claim_uuid",
  "participant_id": "user_123",
  "reward_name": "10% Off Coupon",
  "reward_type": "coupon",
  "code_value": "SAVE10-ABC123",
  "points_deducted": 500,
  "new_balance": 1000
}

Reward types: coupon, voucher, physical, digital, points_multiplier

← Back to Gamification API