> For the complete documentation index, see [llms.txt](https://docs.wynta.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.wynta.com/bonus/architecture/configuration-hierarchy.md).

# Configuration Hierarchy

Bonuses are authored in Wynta under a four-level hierarchy. Budgets cascade downward — a child's caps must not exceed its parent's.

```
Bonus Head  (e.g., "Acquisition")           ── budget caps, owners
  └─ Bonus Subhead  (e.g., "Welcome Offers")── budget caps, owners
       └─ Bonus Configure  (the bonus itself)── amounts, wagering, chunks, validity, caps
            ├─ Promo Codes  (player-facing)  ── display, validity, auto-apply
            ├─ Eligibility Criteria           ── AND-ed player conditions
            └─ Grant Triggers                 ── qualifying player events
```

## Bonus Head

Top-level budget envelope, created with `bonus_create_head`.

* `name` — unique within the site (alphanumeric + space/hyphen/underscore/dot)
* `owner` — primary accountable person (username or email)
* `budget_json` — list of caps, e.g. `[{"period_type": "DAILY", "budget_limit": 5000}]`
  * `period_type`: `DAILY` | `WEEKLY` | `MONTHLY`
  * `budget_limit: null` = uncapped
* Additional owners via `bonus_upsert_head_owners` with roles: `OPS_LEAD`, `CAMPAIGN_MANAGER`, `FINANCE_APPROVER`, `ESCALATION_CONTACT`
* Full change history (including budget updates) via `bonus_get_head_history`

## Bonus Subhead

Created with `bonus_create_subhead` under a head. Same budget format; **limits must not exceed the parent head's caps**. Owners and history endpoints mirror the head level.

## Bonus Configure

The bonus definition itself, created with `bonus_create_configure`. A default promo code `AUTO-{id}` is created automatically alongside it.

| Field                     | Default     | Description                                                                                |
| ------------------------- | ----------- | ------------------------------------------------------------------------------------------ |
| `name`                    | —           | Unique within the subhead                                                                  |
| `start_date`, `end_date`  | —           | Active window (ISO datetime)                                                               |
| `applicability_frequency` | `EVERYTIME` | `EVERYTIME` \| `ONCE` \| `MONTHLY` \| `WEEKLY` — how often a player can receive this bonus |
| `bonus_amount_fixed`      | —           | Fixed grant amount                                                                         |
| `bonus_amount_percent`    | —           | Grant as % of the trigger amount (e.g., % of deposit)                                      |
| `bonus_amount_max`        | —           | Cap on the granted amount                                                                  |
| `wager_multiplier`        | `0`         | Wagering requirement multiplier (`0` = no wagering)                                        |
| `no_of_chunks`            | `1`         | Number of equal release chunks                                                             |
| `chunk_expiry_days`       | —           | Per-chunk expiry                                                                           |
| `bonus_expiry_days`       | —           | Whole-bonus expiry                                                                         |
| `wager_chip_type`         | `CASH`      | Chip type counted for wagering progress                                                    |
| `credit_chip_type`        | `CASH`      | Chip type the bonus is credited in                                                         |
| `priority`                | `0`         | Ordering when multiple configures match (lower = higher priority)                          |
| `release_bucket`          | —           | Optional release bucket identifier                                                         |

Budget caps at this level via `bonus_upsert_configure_limits` (same format as head/subhead).

{% hint style="warning" %}
`bonus_amount_fixed` and `bonus_amount_percent` are alternatives — percent-based bonuses derive the grant from the qualifying event amount (e.g., 100% of first deposit), capped by `bonus_amount_max`.
{% endhint %}

## Promo Codes

Player-facing codes attached to a configure (`bonus_create_configure_code`). One configure can carry several codes (e.g., channel-specific variants).

| Field                                                                                                                                                            | Notes                                                      |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `code`                                                                                                                                                           | 1–50 chars                                                 |
| `valid_from`, `valid_to`                                                                                                                                         | Validity window (ISO datetime)                             |
| `max_amount`                                                                                                                                                     | Per-code cap on bonus amount                               |
| `auto_apply`                                                                                                                                                     | Apply automatically without player entry (default `false`) |
| `display_on`                                                                                                                                                     | Display context, default `DEPOSIT`                         |
| `display_title` (200), `display_description` (500), `terms_url`, `banner_image_url`, `badge_text` (100), `cta_text` (100), `display_order`, `min_display_amount` | Presentation fields the PAM can render directly            |

## Eligibility Criteria

Rows attached to a configure via `bonus_create_eligibility`. **All rows are AND-ed — every criterion must pass** for the player to qualify.

* `eligibility_key` — e.g. `player_registered_period`, `player_type`, `kyc_status`, `min_lifetime_deposits`
* `eligibility_value` — value as a string
* `eligibility_value_type` — `STRING` | `INT` | `DECIMAL` | `BOOLEAN` | `JSON`

## Grant Triggers

{% hint style="info" %}
**Naming note:** the Wynta API calls these *release triggers* (`bonus_create_release_trigger`). Functionally they define the **qualifying player event that awards the bonus** — distinct from the wager-based *chunk release* described in the lifecycle page. This documentation calls them **grant triggers** to avoid confusion.
{% endhint %}

Created per configure, resolved via promo code:

| Field                                      | Notes                                                                                                                             |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `trigger_type`                             | `LOGIN` \| `REGISTRATION` \| `APP_VISIT` \| `DEPOSIT` \| `BET_PLACED` \| `LEADERBOARD_WON` \| `TOURNAMENT_WON` \| `FRIEND_SIGNUP` |
| `occurrence`                               | `0` = every event, `1` = first only, `N` = Nth occurrence                                                                         |
| `min_trigger_amount`, `max_trigger_amount` | Qualifying amount band (e.g., min deposit)                                                                                        |
| `payment_method`                           | Restrict to a method, e.g. `UPI`                                                                                                  |
| `product`                                  | Restrict to a product, e.g. `CASINO`                                                                                              |
| `trigger_config_json`                      | Extra conditions as JSON, e.g. `{"min_deposit": 100}`                                                                             |

**Example — first-deposit bonus:** trigger `DEPOSIT`, `occurrence = 1`, `min_trigger_amount = 100`, on a configure with `bonus_amount_percent = 100`, `bonus_amount_max = 200`, `wager_multiplier = 10`, `no_of_chunks = 5`.