> For the complete documentation index, see [llms.txt](https://docs.terragon.io/documents/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terragon.io/documents/solutions/rewards/base-bonuses.md).

# Base Bonuses

## 1. How It Works

The general bonuses are the backbone of almost all bonuses in the system. In order to be best in scalability it's broken down into smaller parts:

<figure><img src="/files/aEuv6OtRry1zPxy9Y7uX" alt=""><figcaption><p>Bonus Components</p></figcaption></figure>

**Bonus Settings**: this is where we setup bonus rules

**Player Historical Data**: this is where all historical data is stored and used for checking eligibility and bonus validity

**Rule Matching**: this is the center of the bonus system specialize in matching data between bonus settings and player historical data to determine validity of a bonus request.

**Triggers:** this is where operators can control bonus issuance to users automatically

## 2. Bonus Settings

### 2.1 Bonus List

<figure><img src="/files/9z0SIOWvczJpTfJ7HbDL" alt=""><figcaption><p>Bonus List</p></figcaption></figure>

This page is used to list out all created bonuses

<mark style="color:blue;">**Filters**</mark>

<table><thead><tr><th width="215">Field</th><th>Description</th></tr></thead><tbody><tr><td>Bonus code</td><td>Search bonuses by a bonus code</td></tr><tr><td>Bonus Name</td><td>Search bonuses by a bonus name</td></tr><tr><td>Promo Code</td><td>Search bonuses by promo code</td></tr><tr><td>Created Date Period</td><td>Search bonuses created in a time frame</td></tr><tr><td>Category</td><td>Search bonuses by a category</td></tr><tr><td>Status</td><td>Search bonuses by a status. <a data-mention href="/pages/UoSuultp2URjtA6kuZh9">/pages/UoSuultp2URjtA6kuZh9</a></td></tr><tr><td>Award Type</td><td>Search bonuses by an award type. Manual or Automation</td></tr><tr><td>Awarding Condition</td><td>Search bonuses by an awarding condition</td></tr></tbody></table>

<mark style="color:blue;">**Result**</mark>

<table><thead><tr><th width="219">Field</th><th>Description</th></tr></thead><tbody><tr><td>ID</td><td>Bonus ID</td></tr><tr><td>Name</td><td>Bonus name</td></tr><tr><td>Code</td><td>Bonus code</td></tr><tr><td>Statu</td><td>Bonus status</td></tr><tr><td>Category</td><td>Bonus category</td></tr><tr><td>Award Type</td><td>Bonus award type</td></tr><tr><td>Start Date</td><td>Start date of a bonus</td></tr><tr><td>End Date</td><td>End date of a bonus</td></tr><tr><td>Created At</td><td>The time a bonus was created at</td></tr><tr><td>Created By</td><td>Admin user who created the bonus</td></tr><tr><td>Updated At</td><td>The time a bonus was updated</td></tr><tr><td>Updated By</td><td>Admin user who updated the bonus</td></tr><tr><td>Actions</td><td><ul><li>Update: go to Edit Bonus page</li><li>View: view details of a bonus</li><li>Clone: clone the bonus into a new one</li><li>Activate / Deactivate</li></ul></td></tr></tbody></table>

### 2.2 Create/Edit a Bonus

The process of creating a bonus is broken down into 5 steps

#### **2.2.1 General**

<figure><img src="/files/vCZrv1Fe5IVAmYt3ccw0" alt=""><figcaption><p>General</p></figcaption></figure>

<table><thead><tr><th width="145">Field</th><th width="119">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Code</td><td>Yes</td><td>Bonus code</td></tr><tr><td>Name</td><td>Yes</td><td>Bonus name</td></tr><tr><td>Product Type</td><td>Yes</td><td>Mainly has:<br>- Slots (or RNGs)<br>- Live Casino<br>- Sports<br>Product types can be customized upon requests.<br>Defining product types is to determine which games that players can use bonuses to wager, for example: select Sports and Live Casino, players who got the bonus can use it wager on sports and live casino games.</td></tr><tr><td>Exclude Game</td><td>No</td><td>When selecting a game segment for bonus exclusions, players who got the bonus can't use it to wager on the selected games.</td></tr><tr><td>Category</td><td>Yes</td><td>Bonus category. The list can be customized upon requests</td></tr><tr><td>Start</td><td>Yes</td><td>Define the time when a bonus starts</td></tr><tr><td>End</td><td>No</td><td>Define the time when a bonus ends. Empty means bonus has no expiry.</td></tr><tr><td>Redeem Bonus In</td><td>No</td><td>This is used to define how many days players have to finish wagering requirements to make Bonus become Cash (meaning transfer from Bonus balance to Main balance).<br>When failure of achieving this, the system automatically forfeits the bonus</td></tr><tr><td>Expire On</td><td>No</td><td>Setup the exact date that if any players fail in satisfying the wagering requirement before this date, the system will automatically forfeit the bonus.<br>In case both <code>Redeem Bonus In</code> and <code>Expire On</code> are defined, the system will use whichever sooner to apply the logic </td></tr><tr><td>Status</td><td>Yes</td><td>Inactive, Active or Draft</td></tr><tr><td>Description</td><td>Yes</td><td>Bonus description</td></tr><tr><td>Promotion Code</td><td>Yes</td><td>Define a promotion code for players to claim directly on front end</td></tr></tbody></table>

**2.2.2 Eligibility**

<figure><img src="/files/0IwpQP9uQ1Hyv3UnkdEN" alt=""><figcaption><p>Eligibility</p></figcaption></figure>

<table><thead><tr><th width="185">Field</th><th width="123">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Currencies</td><td>Yes</td><td> For players who use a certain currency</td></tr><tr><td>VIP Levels</td><td>Yes</td><td>For players who at a certain VIP level</td></tr><tr><td>Segments</td><td>No</td><td>Upon selected, players in the selected list are eligible for the bonus.<br>In the case that all Currencies, VIP Levels and Segments have values, the system will handle as an AND condition meaning players who are under a certain Currency, at the selected Level and in the selected Segments will be eligible.<br></td></tr></tbody></table>

**2.2.3 Awarding**

<figure><img src="/files/pHZO9qrTvyVRO0MXBlOY" alt=""><figcaption><p>Awarding</p></figcaption></figure>

<table><thead><tr><th width="213">Field</th><th width="143">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td><strong>Awarding Type</strong></td><td></td><td></td></tr><tr><td>Awarding Type</td><td>Yes</td><td><ul><li>Manual: this is used to manually issue at the Backoffice</li><li>Automatic: this is used for players can claim a bonus by themselves on the front end, or system triggers for cashback, rebate,...</li></ul></td></tr><tr><td>Multiple Instance</td><td>No</td><td>Upon checked, the bonus can be claimed multiple times.</td></tr><tr><td>Recurrence Selection</td><td>No</td><td><p>This is visible when selecting Multiple Instance</p><ul><li>None: no recurrence</li><li>Daily: setup a limit for daily</li><li>Weekly: setup a  limit for weekly</li><li>Monthly: setup a limit for monthly</li></ul></td></tr><tr><td><strong>Awarding Condition</strong></td><td></td><td></td></tr><tr><td>Progam Type</td><td>Yes</td><td><ul><li>Standard: issue bonuses to players who acts on something, i.e: deposit, wager,...</li><li>Refer a Friend: issue bonuses to referrer</li></ul></td></tr><tr><td>Condition Type</td><td>Yes</td><td><p>Select condition types. Valid values:</p><ul><li>Deposit<br><img src="/files/1ggpfzxUPoLaYT4c45Jx" alt=""></li><li>Wager/Win/Loss<br><img src="/files/qu0IOZSz6QpNrYklHulX" alt=""></li><li>KYC Verified</li><li>Signup</li><li>None</li><li>VIP Upgrade<br><img src="/files/zjaI2L54abgA8HnE6vVf" alt=""></li></ul></td></tr><tr><td>Payment Options</td><td>No</td><td>Only visible for Deposit bonuses<br>Select a certain payment option that players are eligible when using it to deposit. Leaving empty means all payment options are valid</td></tr><tr><td>Min/Max Deposit</td><td>Only requires if it's Deposit bonuses</td><td><p>Only Visible for Deposit bonuses</p><ul><li>Equivalent: min/max will be checked by converting from fiat to base currency for checking against min/max</li><li>Setup min/max for each currency</li></ul></td></tr><tr><td>Deposit Number</td><td>Only requires if it's Deposit bonuses</td><td><p>Only visible for Deposit Bonuses.</p><p>Checking against the sequences of players' deposit.</p><p>Valid operator: >, =</p><p>For example: = 1 meaning first time deposit of players.<br>>1 meaning 2nd deposits onwards</p></td></tr><tr><td>Min/Max wagers</td><td>Only requires if it's Wager bonuses</td><td>Only visible for Wager Bonuses.<br>The setup for Equivalent and per currency is similar to Deposit bonus</td></tr><tr><td>In Period</td><td>Yes</td><td>Only visible for Wager Bonuses.<br>Select a period of time when players play to calculate toward min/max conditions.<br>Valid values:<br>- Once: when selecting once it's required to select a date time range:<br><img src="/files/98VWWlqeDRfTejtddy8c" alt=""><br>- Daily<br>- Weekly<br>- Monthly<br>When selecting Daily, Weekly, Monthly it's required to select a specific time zone which the system will use to calculate bets made daily, weekly or monthly of a specified timezone.</td></tr><tr><td>Game Segment</td><td>Yes</td><td>To select a game list played by players to calculate toward min/max conditions</td></tr><tr><td>Exclude</td><td>No</td><td><ul><li>Cashout</li><li>Odds below</li></ul><p>This is for sports, we can exclude bets has Cashout status and odds below a certain number from the calculation</p></td></tr><tr><td><strong>Bonus Amount Setup</strong></td><td></td><td></td></tr><tr><td>In Game Reward</td><td>No</td><td><p><img src="/files/YZops9iajy4GBdS0rELX" alt="" data-size="original"></p><p>This is used to setup in-game bonuses with game providers.</p><p></p><ul><li>Type: Free Round (Free spins), Free Money (used for Live casino)</li><li>Game Provider: select a game provider integrated with their bonus</li><li>Total Free Round: define a number of free rounds</li><li>Define value for each free round under a specific currency</li><li>Select Games: to select games available for the free spin bonuses</li><li>Advance: this is used to custom parameters sent to each game provider </li></ul></td></tr><tr><td>Award As</td><td>Yes</td><td><ul><li>Fixed Amount<br><img src="/files/YCEp3T8bmL4kCVUCHhys" alt="">Define a fix bonus amount given to players.</li><li>% of Amount<img src="/files/dlspdIUoZgLtAlnIdTa1" alt=""><br>Define a percentage based on players' actions, i.e: deposits, wager, win, loss</li><li>Any Amount: this is only visible when selecting Awarding Type of Manual. This is used to manually issue a arbitrary bonus amount to a player<br><img src="/files/e9GrYFvyrGFGAvBhsWZ8" alt=""></li></ul></td></tr><tr><td>Up to max amount</td><td>No</td><td>Define maximum amount given to a player.<br>Similar to any other amount inputs, it supports:<br>- Equivalent: the system automatically convert based on based currency<br>- Per currency</td></tr><tr><td>Max Wager Amount</td><td>No</td><td>Define maximum of bet amounts when using Bonus funds for wager</td></tr><tr><td>Apply Bonus as Pending</td><td>No</td><td>When checked, the system won't issue the bonus directly to their bonus wallets, but require players to claim it at a reward section on the front end.</td></tr><tr><td>Allow Addon Bonus</td><td>No</td><td>Define a bonus for players claim it as an extra, i.e: Welcome Bonus + 10 Freespins</td></tr></tbody></table>

Rules of issuing bonuses to players' wallets:

* Players have multiple crypto/fiat wallets, bonus amount will be issued directly to the wallets players use to deposit. For example: if players deposit by BTC and claim for FTD they'll get their bonuses credited to their BTC wallet.
* Players can wager on multiple wallets, i.e: BTC, ETH,... for wager/win/loss bonuses the system will credit to the latest usage of bets, using the latest exchange rate before converting to the last usage wallet currency.

**2.2.4 Wagering Requirement**

<figure><img src="/files/VWhjrbXx5nt5j2HfoV4v" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="223">Field</th><th width="121">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Bonus has wagering requirement</td><td>No</td><td><ul><li>Selected: the bonus will create a wagering requirement after players got a bonus</li><li>Not Selected: the bonus won't create a wagering requirement when players got a bonus, and it transfers to Main wallet immediately.</li></ul></td></tr><tr><td>Wagering Multiplier</td><td>Yes</td><td>Multiply number</td></tr><tr><td>Multiply To</td><td>Yes</td><td>To setup multplier for the wagering requirement</td></tr><tr><td>Game Segments</td><td>Yes</td><td>To define list of games contributed toward a wagering requirement</td></tr><tr><td>Engine</td><td>Yes</td><td>Only visible for Deposit bonuses<br><a data-mention href="/pages/0EbxF5LKLtlLB3qnPvwu">/pages/0EbxF5LKLtlLB3qnPvwu</a></td></tr><tr><td>Max Claimable Amount</td><td>No</td><td>Setup bonus cap that players can redeem when hitting the wagering requriement.</td></tr></tbody></table>

**2.2.4 Liability**

This is for operators to limit the budget of bonuses given to players

<figure><img src="/files/G7I8vgpjeW0jeQqBF8Gt" alt=""><figcaption><p>Liability</p></figcaption></figure>

<table><thead><tr><th width="184">Field</th><th width="123">Mandatory</th><th>Description</th></tr></thead><tbody><tr><td>Limit Bonus</td><td>No</td><td>To enable limiting bonus budget</td></tr><tr><td>Total Number of awarded bonuses</td><td>No</td><td>Limit a number of bonuses awarding to players</td></tr><tr><td>Limit  Amount</td><td>No</td><td>Limit a bonus amount in total given to player</td></tr></tbody></table>