Points API

Award and deduct points, query balances, and view transaction history. Points trigger automatic tier evaluation — if a participant crosses a tier threshold, the tier upgrade is included in the response.

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

Method	Endpoint	Description
POST	`/gamify/points/award`	Award points. Returns new balance and any tier upgrade.
POST	`/gamify/points/deduct`	Deduct points. Returns 400 if insufficient balance.
POST	`/gamify/points/award-batch`	Batch award up to 100 participants at once.
GET	`/gamify/participants/{pid}/points`	Get current balance, total earned, and total spent.
GET	`/gamify/participants/{pid}/points/transactions`	Paginated transaction history.

Award Points

Request

POST /api/v1/gamify/points/award

{
  "participant_id": "user_123",    // Required, 1-255 chars
  "amount": 100,                   // Required, 1-1,000,000
  "reason": "Purchase completed",  // Optional, max 500 chars
  "metadata": {                    // Optional, custom data
    "order_id": "ord_abc",
    "amount_usd": 49.99
  },
  "idempotency_key": "purchase_ord_abc"  // Optional, prevents duplicates
}

Response

{
  "transaction_id": "a1b2c3d4-e5f6-...",
  "participant_id": "user_123",
  "amount": 100,
  "new_balance": 1500,
  "tier_upgrade": {                // null if no tier change
    "code": "gold",
    "name": "Gold Tier",
    "level": 3,
    "previous_code": "silver",
    "previous_level": 2
  }
}

Deduct Points

POST /api/v1/gamify/points/deduct

{
  "participant_id": "user_123",
  "amount": 50,
  "reason": "Reward redemption"
}

// Response
{
  "transaction_id": "...",
  "participant_id": "user_123",
  "amount": 50,
  "new_balance": 1450
}

// Error: insufficient balance
// 400 Bad Request
{ "detail": "Insufficient points. Available: 30, requested: 50" }

Batch Award

Award points to up to 100 participants in a single request. Each award is processed independently — individual failures do not affect other awards in the batch.

POST /api/v1/gamify/points/award-batch

{
  "awards": [
    { "participant_id": "user_1", "amount": 100, "reason": "Weekly bonus" },
    { "participant_id": "user_2", "amount": 100, "reason": "Weekly bonus" },
    { "participant_id": "user_3", "amount": 50, "reason": "Referral bonus" }
  ]
}

// Response
{
  "processed": 3,
  "failed": 0,
  "results": [
    { "participant_id": "user_1", "transaction_id": "...", "new_balance": 500, "error": null },
    { "participant_id": "user_2", "transaction_id": "...", "new_balance": 350, "error": null },
    { "participant_id": "user_3", "transaction_id": "...", "new_balance": 200, "error": null }
  ]
}

Balance and Transactions

// Get current balance
GET /api/v1/gamify/participants/user_123/points

{
  "participant_id": "user_123",
  "balance": 1500,
  "total_earned": 5000,
  "total_spent": 3500
}

// Transaction history (paginated)
GET /api/v1/gamify/participants/user_123/points/transactions?page=1&page_size=20

{
  "transactions": [
    {
      "transaction_id": "txn_abc",
      "type": "award",
      "amount": 100,
      "reason": "Purchase completed",
      "balance_after": 1500,
      "created_at": "2026-02-14T10:00:00Z"
    }
  ],
  "total": 156,
  "page": 1,
  "page_size": 20
}

← Back to Gamification API