Bonuses reference
Issue promotional balances backed by a balanced bonus-liability ledger. Convert automatically when wagering targets are hit.
Supported types
| type | What it is | Key fields |
|---|---|---|
no_deposit | Flat bonus amount, no deposit required | amount, wagering_multiple |
deposit_match | Match a deposit by % up to a cap (e.g. "100% up to $500") | amount_pct, max_amount, wagering_multiple |
free_spins | N free spins on a specified game | free_spin_count, wagering_multiple |
cashback | Returns a % of net loss | amount_pct, wagering_multiple |
reload | Periodic deposit-match for retention | amount_pct, max_amount |
rakeback | % of contributed rake (sportsbook / poker) | amount_pct |
lossback | Net-loss refund (no wagering) | amount_pct |
referral | Granted on confirmed referral | amount |
vip_comp | VIP-tier loyalty grant | amount |
ticket | Tournament / raffle entry | amount |
drops | Lootbox / mini-game drop | amount |
manual | Operator-defined, escape hatch | any |
Grant a bonus
POST /v1/bonuses/grant
{
"player_id": "StarlordV7",
"template": "WELCOME200", // promo_code OR template uuid
"idempotency_key": "grant-2025-05-19-001"
}
# 201
{
"bonus": {
"id": "…",
"player_id": "StarlordV7",
"type": "deposit_match",
"status": "active",
"bonus_amount": 500.00,
"wagering_required": 15000.00,
"wagering_completed": 0.00
},
"deduped": false
}Wagering & conversion
Each wager event you fire on a bonus-eligible player advances wagering_completed. When it reaches wagering_required, the bonus auto-converts: the locked bonus balance flips to real, balanced as a single ledger entry.
Bonus lifecycle states
pending | Awaiting opt-in / deposit |
active | Counting wagering toward the target |
completed | Converted to real balance |
expired | Time-window elapsed; remaining bonus removed |
forfeited | Operator-revoked (fraud, abuse) |
cancelled | Player-cancelled before activation |