Reward Configuration Guide

This guide provides detailed examples for configuring rewards across different Phoenix features.

Quick Reference

Feature	Uses Reward Items Via	Distribution Trigger
Coupons	`reward_item_id` in coupon config	User redeems coupon code
Leaderboards	`reward_config_id` with tiers	Window completion
Streaks	`reward_config_id` with tiers	Milestone reached
Achievements	`reward_config_id` with tiers	Achievement completed

1. Creating Reward Items

Before configuring any feature, create the reward items in your library.

Currency Rewards

POST /v1/tenants/{tenant_id}/reward-items

{
  "name": "500 Gold Coins",
  "description": "Standard gold coin reward",
  "reward_type": "currency",
  "payload": {
    "currency_id": "gold",
    "amount": 500
  }
}

Virtual Items

{
  "name": "Legendary Chest",
  "description": "Contains rare items",
  "reward_type": "item",
  "payload": {
    "item_id": "legendary_chest",
    "quantity": 1
  }
}

Badges/Achievements

{
  "name": "Weekly Champion",
  "description": "Awarded to #1 weekly player",
  "reward_type": "badge",
  "payload": {
    "badge_id": "weekly_champion_2025",
    "tier": "gold"
  }
}

Physical Prizes

{
  "name": "iPhone 15 Pro",
  "description": "256GB Space Black",
  "reward_type": "physical_item",
  "payload": {
    "model": "iPhone 15 Pro",
    "storage": "256GB",
    "color": "Space Black",
    "shipping_required": true,
    "estimated_value_usd": 999
  }
}

2. Coupon Configuration

Coupons directly reference a single reward item.

Basic Coupon

{
  "name": "Daily Login Bonus",
  "config": {
    "reward_item_id": "gold-500-item-id",
    "code_format": "random",
    "code_length": 8,
    "usage_limit": {"limit_type": "per_user", "max_uses": 1}
  }
}

Promotional Campaign

{
  "name": "New Year 2025 Special",
  "config": {
    "reward_item_id": "legendary-chest-item-id",
    "code_format": "custom",
    "custom_code": "NEWYEAR2025",
    "starts_at": "2025-01-01T00:00:00Z",
    "expires_at": "2025-01-07T23:59:59Z",
    "usage_limit": {"limit_type": "unlimited"}
  }
}

3. Leaderboard Reward Config

Leaderboards use reward configs with rank-based tiers.

Same Reward for All in Range

All players in the rank range get the same items:

{
  "name": "Top 10 Gems Reward",
  "tiers": [
    {
      "condition": {"type": "rank_range", "start": 1, "end": 10},
      "item_ids": ["gems-5000-item-id"]
    }
  ]
}

Different Rewards per Rank

Different prizes for each position:

{
  "name": "Tournament Grand Prizes",
  "tiers": [
    {
      "condition": {"type": "rank_range", "start": 1, "end": 3},
      "rank_items": {
        "1": ["macbook-item-id", "champion-badge-id"],
        "2": ["iphone-item-id", "runner-up-badge-id"],
        "3": ["samsung-item-id", "third-place-badge-id"]
      }
    },
    {
      "condition": {"type": "rank_range", "start": 4, "end": 10},
      "item_ids": ["gems-5000-item-id"]
    },
    {
      "condition": {"type": "rank_range", "start": 11, "end": 100},
      "item_ids": ["gems-1000-item-id"]
    }
  ]
}

Multiple Items per Rank

Give multiple rewards to winners:

{
  "tiers": [
    {
      "condition": {"type": "rank_range", "start": 1, "end": 1},
      "item_ids": [
        "champion-badge-id",
        "gems-10000-item-id",
        "legendary-chest-item-id"
      ]
    }
  ]
}

4. Streak Reward Config

Streaks use threshold and milestone conditions.

Milestone Rewards

Exact day achievements:

{
  "name": "Streak Milestones",
  "tiers": [
    {
      "condition": {"type": "milestone", "metric": "streak_days", "value": 7},
      "item_ids": ["week-warrior-badge-id", "gold-500-item-id"]
    },
    {
      "condition": {"type": "milestone", "metric": "streak_days", "value": 30},
      "item_ids": ["month-master-badge-id", "gems-5000-item-id"]
    },
    {
      "condition": {"type": "milestone", "metric": "streak_days", "value": 100},
      "item_ids": ["legend-badge-id", "legendary-chest-item-id"]
    }
  ]
}

Range-Based Rewards

Rewards for being within a streak range:

{
  "name": "Streak Tier Rewards",
  "tiers": [
    {
      "condition": {"type": "threshold_range", "metric": "streak_days", "min": 7, "max": 13},
      "item_ids": ["gold-500-item-id"]
    },
    {
      "condition": {"type": "threshold_range", "metric": "streak_days", "min": 14, "max": 29},
      "item_ids": ["gold-1000-item-id"]
    },
    {
      "condition": {"type": "threshold_range", "metric": "streak_days", "min": 30, "max": 999},
      "item_ids": ["gold-2000-item-id"]
    }
  ]
}

5. Attaching Configs to Features

Attach to Leaderboard

POST /v1/tenants/{tenant_id}/leaderboards

{
  "leaderboard_id": "weekly-xp",
  "name": "Weekly XP Competition",
  "reward_config_id": "your-reward-config-id",
  "config": {...}
}

Attach to Streak

POST /v1/tenants/{tenant_id}/streaks

{
  "name": "Daily Login Streak",
  "reward_config_id": "your-reward-config-id",
  "config": {...}
}

6. Validation Rules

Reward Items

Field	Requirement
`name`	Required, non-empty
`reward_type`	Required, non-empty string
`payload`	Required, can be empty `{}`

Reward Config Tiers

Rule	Description
At least one tier	Config must have ≥1 tier
Item IDs XOR Rank Items	Each tier uses `item_ids` OR `rank_items`, not both
Valid conditions	`rank_range`: start ≤ end, both ≥ 1
	`threshold_range`: min ≤ max
Rank items in range	If using `rank_items`, keys must be within condition range

Example Validation Errors

// ❌ Error: Tier must have either item_ids or rank_items
{
  "condition": {"type": "rank_range", "start": 1, "end": 3}
  // Missing item_ids or rank_items
}

// ❌ Error: Cannot have both item_ids and rank_items
{
  "condition": {"type": "rank_range", "start": 1, "end": 3},
  "item_ids": ["item-1"],
  "rank_items": {"1": ["item-2"]}
}

// ❌ Error: Rank 5 is outside condition range (1-3)
{
  "condition": {"type": "rank_range", "start": 1, "end": 3},
  "rank_items": {"5": ["item-1"]}
}

7. Webhook Payloads

Leaderboard Completion

{
  "event_type": "leaderboard.window_completed",
  "tenant_id": "your-tenant-id",
  "leaderboard_id": "weekly-xp",
  "window_key": "2025-W02",
  "reward_distribution": [
    {
      "user_id": "user-123",
      "rank": 1,
      "score": 12850,
      "items": [
        {"item_id": "...", "name": "...", "reward_type": "...", "payload": {...}}
      ]
    }
  ]
}

Streak Milestone

{
  "event_type": "streak.milestone_reached",
  "tenant_id": "your-tenant-id",
  "streak_id": "daily-login",
  "user_id": "user-123",
  "streak_days": 30,
  "items": [
    {"item_id": "...", "name": "Month Master Badge", "reward_type": "badge", ...}
  ]
}

Coupon Redeemed

{
  "event_type": "coupon.redeemed",
  "tenant_id": "your-tenant-id",
  "user_id": "user-123",
  "code": "WELCOME8X4F2K9P",
  "reward_item": {
    "item_id": "...",
    "name": "500 Gold Coins",
    "reward_type": "currency",
    "payload": {"currency_id": "gold", "amount": 500}
  }
}

Next Steps

Rewards Overview - Core concepts
Creating Coupons - Coupon integration
Creating Leaderboards - Leaderboard integration

Reward Configuration Guide

On this page