Promotions & Bonuses

The Promotions module handles all marketing campaigns, bonus claims, and wagering tracking.

Like other modules, this is fully dynamic. The backoffice can create any type of promotion (Match Bonus, Free Spins, Cashback) with custom rules, and the SDK will deliver it to the frontend without hardcoding the logic.

Fetching Available Promotions

Fetch a list of currently active campaigns to display on your promotions page.

const promotions = await sdk.promotions.getPromotions();

promotions.forEach(promo => {
  console.log(`${promo.name} (${promo.type})`);
  console.log(`Rules:`, promo.rules);
  // Example rules: { minDeposit: 20, maxBonus: 500, wageringMultiplier: 30 }
});

Claiming a Promotion

When a user clicks "Claim" on a promotion, the backend validates the rules and creates an active PlayerBonus in their wallet.

try {
  const activeBonus = await sdk.promotions.claimPromotion('promo_welcome_100');
  console.log(`Bonus claimed! You need to wager $${activeBonus.wageringRequirement} to unlock.`);
} catch (error) {
  console.error(error.message); // e.g., "Promotion already claimed."
}

Tracking Wagering Progress

Once a bonus is claimed, the frontend can display a progress bar showing how much the user still needs to bet to convert the bonus into real, withdrawable cash.

const activeBonuses = await sdk.promotions.getActiveBonuses();

activeBonuses.forEach(bonus => {
  const progress = (bonus.wageredAmount / bonus.wageringRequirement) * 100;
  console.log(`${bonus.promotionName}: ${progress}% complete`);
  console.log(`Remaining to wager: $${bonus.remainingWager}`);
});

Forfeiting a Bonus

If a user wants to withdraw their real cash but is blocked by an active bonus wagering requirement, they can choose to forfeit the bonus.

// Warning: Forfeiting usually removes the bonus money from the wallet immediately.
await sdk.promotions.forfeitBonus('bonus_12345');