Skip to main content

Rewards API

The Rewards API allows you to manage user rewards, badges, points, and challenges.

Record Event​

Record a user event that may trigger rewards or badge progress.

Endpoint: POST /rewards/events

Headers:

  • X-F-Authorization: Client token (required)
  • X-F-Authentication: User token (required)

Request Body:

{
  "event_type": "festival_attended",
  "entity_type": "festival",
  "entity_id": "festival-id",
  "metadata": {
    "additional": "data"
  }
}

Response:

{
  "event_id": "event-id",
  "points_awarded": 100,
  "badges_progressed": ["badge-id"]
}

Get User Points​

Get the current user's points balance.

Endpoint: GET /rewards/points

Headers:

  • X-F-Authorization: Client token (required)
  • X-F-Authentication: User token (required)

Response:

{
  "balance": 1500,
  "total_earned": 2000,
  "total_spent": 500
}

Get User Badges​

Get all badges for the authenticated user.

Endpoint: GET /rewards/badges

Headers:

  • X-F-Authorization: Client token (required)
  • X-F-Authentication: User token (required)

Response:

[
  {
    "id": "badge-id",
    "name": "Festival Explorer",
    "description": "Attend 10 festivals",
    "icon": "https://example.com/icon.png",
    "progress": {
      "current": 7,
      "target": 10,
      "percentage": 70
    },
    "unlocked": false
  }
]

Claim Challenge​

Claim a challenge using a claim code.

Endpoint: POST /rewards/challenges/claim/:code

Headers:

  • X-F-Authorization: Client token (required)
  • X-F-Authentication: User token (required)

Response:

{
  "challenge_id": "challenge-id",
  "points_awarded": 500,
  "message": "Challenge claimed successfully"
}

Get User Level​

Get the current user's level and benefits.

Endpoint: GET /rewards/level

Headers:

  • X-F-Authorization: Client token (required)
  • X-F-Authentication: User token (required)

Response:

{
  "level": 5,
  "points": 1500,
  "next_level_points": 2000,
  "benefits": [
    {
      "id": "benefit-id",
      "name": "Early Access",
      "description": "Get early access to ticket sales",
      "active": true
    }
  ]
}