> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/general-concepts/bonuses.md).

# Bonuses

### Overview

Smartico is getting the list of the available bonuses from the platform and is issuing the bonuses through the platform using an API. The general logic of such API look like "Give bonus X to the user Y", where the bonus X is identified by some unique name or ID, and all details of the bonus are managed on the side of the integrated system.

For example: For a Casino product, the bonus can be identified as '10FREE\_SPIN\_IN\_GOLDEN\_SLOT'. Information about the number of spins and eligible games is managed on the Casino system side, and the Smartico system will only instruct the casino through the API to give 10FREE\_SPIN\_IN\_GOLD\_SLOT to the user John1984.

{% hint style="info" %}
Keep in mind that a player can get only a limited number of bonuses per day (UTC). Bonuses that were redeemed or are still waiting count; failed bonuses do not. When the limit is reached, the system will refrain from granting additional bonuses until the next day. The limit is set by the **Max bonuses per player per day** setting (20 or 50 by default, depending on your Smartico server). See [Bonus Amount CAPs](#bonus-amount-caps).
{% endhint %}

Operators can give bonuses to the end users in the following ways:

* from [campaigns](/welcome/products/crm-automation/create-journey-flow.md)
* from [automation rules](/welcome/products/crm-automation/automation-rules.md)
* from [mini-games](/welcome/products/mini-games.md)
* from [missions](/welcome/products/gamification-basics/missions.md)
* from [tournaments](/welcome/products/gamification-basics/tournaments.md)
* from the [store](/welcome/products/gamification-basics/marketplace.md) (where players can buy it as a store item)

You can also control which bonuses to display for the end users in the Gamification Widget. We have added the possibility to:

* show only bonuses given by specific products (Shop, Mini-game, Automation rule, etc.)
* show only bonuses with particular status (Redeemed, Redeem Failed, etc.)
* show a combination of bonuses given by specific products and with particular status

By default the option is disabled, meaning that all bonuses are visible in the gamification widget (regardless of status or where they come from).

{% hint style="info" %}
You set these filters in **Label settings** → **Widget / Real users** (and **Widget / Test users**) → **Bonuses**: **Show only bonuses given by products** and **Show only bonuses in the status**. The same section has **Show bonus history for last X days**. If you cannot change these settings, please get in touch with your Customer Success Manager.
{% endhint %}

### Bonus Types and Bonus Templates

Bonus types are configurable on the platform’s side. They could be for example Cash bonuses, Free Spins, or Coupon Code. To issue a bonus with Smartico, the operator should create a bonus template in our BO, where the bonus type should be added. In the template, there are options to set an icon, public name (how the bonus will be displayed to end-users), bonus activity period (active from/till), bonus type (cash bonus, free spins), and expiration period (**Bonus will expire in**, up to 30 days; shown only for platforms where players redeem their bonuses later).

If a bonus template has no expiration period of its own, the **Default bonus expiration, days** setting in **Label settings** is used (0 by default, which means the bonus does not expire). It is used only for integrations where players redeem their bonuses later; ask your Success manager to change it.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-8655268a8cefef9f01f778c3eb604d74e6d86082%2FBonusesIMG.png?alt=media" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FDaFtQSyoaZHIt1Wlg32G%2F01139eaa57-shot-2-87a3c802-0149a1.png?alt=media" alt=""><figcaption><p>General section of a bonus template: 1 — Internal name, 2 — Bonus cost (EUR), 3 — Bonus amount limit, 4 — Bonus activity period</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-17d06767741271f58ae6b08302a872d4afc0aeef%2FBonus%20Template%202.png?alt=media" alt=""><figcaption><p>Example of Bonus Template in Smartico BO</p></figcaption></figure></div>

Once the bonus template is created, it can be given to the end-user via Campaign, Automation Rule, Mission, Tournament, Mini-games or to be added as a Store item, from where the players can buy it. Keep in mind that when giving a bonus, some properties from the bonus template can be overridden, for example, Coupon Code, Bonus Amount, and UI Name of the bonus (the name that will be displayed in the gamification widget).

For example, if there is already an existing bonus template in Smartico BO with the public name ‘Free Spins’, once the operator adds the bonus template as a prize from a specific mini-game, for instance, they can override the name and the amount.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-318ec568708723d3bc8b89163fe57ce058a8a28e%2FScreenshot_32.png?alt=media" alt=""><figcaption><p>Example of Bonus set as a prize in mini-game</p></figcaption></figure></div>

### Bonus Amount CAPs

The Bonus Caps allow you to limit the number and the total cost of bonuses that one player can get per day (UTC). Once the cap is reached, no further bonuses will be given until the next day.

{% hint style="success" %}
The cap on the total bonus cost (**Max total bonus cost per player per day**) is based on the 'Bonus Cost' field that must be defined. If Bonus Cost is not set, this cap will not be applied. The caps on the number of bonuses apply to all bonuses, with or without a Bonus Cost, unless **Ignore bonus CAPs** is used (see below). By default, jackpot bonuses also skip the caps.
{% endhint %}

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-32c3bb8ca8d3e5912bc7227ad1583054b9a3064a%2FScreenshot_8.png?alt=media" alt=""><figcaption></figcaption></figure></div>

#### How to setup

You can setup different cap settings in **Label settings** or custom **per Brand**:

* **Max bonuses per test player per day** - defines the **max number** (*not amount*!) of bonuses that can be issued to one test user per day (UTC)
* **Max bonuses per player per day** - defines the **max number** of bonuses that can be issued to one real user per day (UTC)
* **Max total bonus cost per player per day** - Smartico will block awarding of bonuses once the set daily limit is reached (calculated based on UTC). This cap applies only to bonuses with a defined **Bonus cost**, which must be specified in the Label's base currency. If the setting is empty, there is no limit. For example:
  * If the daily bonus cap is set to $1000, and this amount is reached, any further attempts to issue bonuses will be rejected
  * If the daily bonus cap is set to $100 and a player has already received a $10 bonus, and an operator tries to give an additional $91 bonus, it will be rejected (total = $101). However, giving $90 or less would succeed.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FYwgxGti8wuyClJdOTahh%2Ffd51a07e18-shot-6-2149b3ad-ff8297.png?alt=media" alt=""><figcaption><p>Bonus caps in Label, settings → System settings → Bonuses: 1 — test players, 2 — real players, 3 — total bonus cost per player per day</p></figcaption></figure></div>

**Important Notes**

* If both the Bonus Amount CAP and the bonus template limit (**Bonus amount limit**) are defined:
  * The lower value takes precedence.
  * Example: If the bonus cap is $100 and the bonus template limit allows $120, the player can receive a maximum of $100.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2FjofAxER2z2yuJsDDm7ZV%2F231fc9a10e-crop-7-5cd0f835-d88d15.png?alt=media" alt=""><figcaption></figcaption></figure></div>

### Bonus Statuses

The lifecycle of the ‘bonus’ when the Smartico system issues it is as follows:

* **New** - the original status of the bonus when it's just created in the Smartico system. The bonus stays in this status until it's transitioned either to "Redeemed" or "Redeem failed". If a technical problem on the Smartico side stopped the bonus from being sent to the platform, the system tries to issue it again every 10 minutes during the retry period set by Smartico; If the bonus is not issued by the end of the retry period, the status remains ‘New’. When the bonus is in this status, it’s not visible to the end user in the gamification widget;

{% hint style="info" %}

* By default, a bonus that the platform rejects becomes **'Redeem Failed'** at once. If the **Retry bonuses rejected by the platform** setting in **Label settings** is ON, a rejected bonus stays in status **NEW** and is sent again every 10 minutes during the retry period; if the last attempt still fails, the status is changed to **'Redeem Failed'.** Bonuses bought in the Store are never retried.
* This setting should be ON only if the platform bonus API is protected against duplicate bonuses; ask your Success manager to change it.
  {% endhint %}

- **Redeem Failed** - when the bonus cannot be redeemed because the Operator's platform rejects it. For example, if a user gets a bonus from a mission or a tournament (not from the Store) the PAM system rejects it with the reason 'User has another bonus', the bonus will be in ‘Redeemed Failed’ status and will be visible to the end-user in the gamification widget. From this state, depending on the integration with the platform the player can try to redeem the bonus from the Bonuses section in the gamification widget.
- **Redeemed** - the final successful state of the bonus, when the Operator's platform processed the request to give a bonus;

{% hint style="info" %}

* Some bonus statuses depend on the bonus engine provided by the operators' system.
* The possibility of redeeming a bonus by the end-user depends on the integration. Not every platform provides the option to redeem the bonus after it's failed once.
* When the user purchases a bonus connected to a store item but fails to be issued (the bonus is in status New or Redeem Failed), there is a possibility of returning points to the client (the **Refund points when a store bonus fails** setting in **Label settings**, ON by default).
* The Operator can hide the bonus visibility for the players, so bonuses will not be displayed in the gamification widget at all (the **Hide bonuses in the gamification widget** setting in **Label settings**).
  {% endhint %}

A bonus for a player whose account status is not Active or Pending is not sent to the platform and gets the status **Redeem Failed**, unless the **Give bonuses to non-active players** setting in **Label settings** is ON.

If the **Block bonus redemption in the widget** setting in **Label settings** is ON, players still see their bonuses in the Bonuses section of the gamification widget, but get an error message when they try to redeem them; ask your Success manager to change it.

### Redirect from Bonuses in the GF widget

You can redirect users directly from Bonuses in the Gamification Widget. The ‘Redirect to’ field is available under **Bonus Template → Presentation in the Gamification Widget**, where you can add a deep link to define the redirection target. By default, this field is empty, meaning no redirection will occur unless a link is specified.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2F1hDxB9v57e45rMOHO1k1%2F452606cd08-crop-8-a6433281-9607fe.png?alt=media" alt=""><figcaption><p>BO: 'Redirect to' option in Bonus templates</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2Fgit-blob-2ad654885a6d3bd33bb6a6dde3e7ef7b897f9caa%2FScreenshot_22.png?alt=media" alt=""><figcaption><p>GF Widget: Redirection from bonuses</p></figcaption></figure></div>

### Issue Bonus from Template

You can issue a bonus directly from the bonus template. This makes it easy to test a bonus template by manually issuing a specific bonus to a selected user. The 'Manual Issue' button is available within the bonus template. Note that this option is intended primarily for testing purposes.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2F1u12g1jqxtVvrM9ZHLmK%2F42be46c8ed-crop-10-6308bc6e-64a0d4.png?alt=media" alt=""><figcaption><p>BO: Manual bonus issue from Template</p></figcaption></figure></div>

### Ignore bonus CAPs

You can ignore bonus CAPs when issuing a bonus with the **'Ignore bonus CAPs'** option. When enabled, the bonus will be issued even if its CAP has already been reached. The option is available in all places where bonuses can be issued, including Campaigns, Automation Rules, Missions, Badges, Tournaments, Store, Mini-games, etc. By default, the option is disabled, meaning the bonus will not be issued once the CAP is reached.

<div data-with-frame="true"><figure><img src="https://77049817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfS5hl0PiysHtKAKMsQTe%2Fuploads%2F3uCOMVuyiE91gEQKylJ9%2FScreenshot_19.png?alt=media&amp;token=9b8beccf-4980-4742-b87f-756045052a37" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.smartico.ai/welcome/products/general-concepts/bonuses.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.