> 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/terragon-api-document/bonus.md).

# Bonus

Player bonuses and promotions

## Get player bonuses

> Retrieve active bonuses for the current player

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Bonus","description":"Player bonuses and promotions"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"last_page":{"type":"integer","description":"Last page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of items"},"data":{"type":"array","description":"Collection of items for the current page","items":{"type":"object"}}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/bonuses":{"get":{"tags":["Bonus"],"summary":"Get player bonuses","description":"Retrieve active bonuses for the current player","operationId":"getPlayerBonuses","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","default":10}},{"name":"status","in":"query","required":false,"description":"Filter by status","schema":{"type":"string","enum":["active","completed","expired"]}}],"responses":{"200":{"description":"Player bonuses retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationMeta"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Claim bonus

> Claim a specific bonus

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Bonus","description":"Player bonuses and promotions"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PlayerBonus":{"type":"object","properties":{"id":{"type":"integer","description":"Player bonus ID"},"player_id":{"type":"integer","description":"Player ID"},"bonus_id":{"type":"integer","description":"Bonus ID"},"wagering_requirement_id":{"type":"integer","description":"Wagering requirement ID"},"bonus":{"$ref":"#/components/schemas/Bonus"},"amount":{"type":"number","format":"float","description":"Bonus amount"},"currency_code":{"type":"string","description":"Currency code"},"wagering_amount":{"type":"number","format":"float","description":"Wagering amount"},"wagering_remaining":{"type":"number","format":"float","description":"Remaining wagering amount"},"expires_at":{"type":"string","format":"date-time","description":"Bonus expiration timestamp"},"created_at":{"type":"string","format":"date-time","description":"Bonus creation timestamp"},"status":{"type":"string","enum":["active","completed","expired","cancelled"],"description":"Bonus status"}}},"Bonus":{"type":"object","properties":{"id":{"type":"integer","description":"Bonus ID"},"name":{"type":"string","description":"Bonus name"},"description":{"type":"string","description":"Bonus description"},"type":{"type":"string","enum":["deposit","no_deposit","free_spin"],"description":"Bonus type"},"min_deposit":{"type":"number","format":"float","description":"Minimum deposit required"},"max_amount":{"type":"number","format":"float","description":"Maximum bonus amount"},"wagering_multiplier":{"type":"number","format":"float","description":"Wagering requirement multiplier"},"validity_days":{"type":"integer","description":"Validity period in days"},"is_active":{"type":"boolean","description":"Whether the bonus is active"}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/bonuses/{bonusId}/claim":{"put":{"tags":["Bonus"],"summary":"Claim bonus","description":"Claim a specific bonus","operationId":"claimBonus","parameters":[{"name":"bonusId","in":"path","required":true,"description":"Bonus ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Bonus claimed successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayerBonus"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bonus not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Cancel active bonus

> Cancel an active bonus by its wagering requirement ID

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Bonus","description":"Player bonuses and promotions"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}},"paths":{"/v1/bonuses/{wageringRequirementId}/cancel":{"put":{"tags":["Bonus"],"summary":"Cancel active bonus","description":"Cancel an active bonus by its wagering requirement ID","operationId":"cancelBonus","parameters":[{"name":"wageringRequirementId","in":"path","required":true,"description":"Wagering requirement ID","schema":{"type":"integer"}}],"responses":{"200":{"description":"Bonus cancelled successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Bonus not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

## Get promotions

> Retrieve available promotions

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Bonus","description":"Player bonuses and promotions"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"paths":{"/v1/promotions":{"get":{"tags":["Bonus"],"summary":"Get promotions","description":"Retrieve available promotions","operationId":"getPromotions","parameters":[{"name":"page","in":"query","required":false,"description":"Page number for pagination","schema":{"type":"integer","default":1}},{"name":"per_page","in":"query","required":false,"description":"Number of items per page","schema":{"type":"integer","default":10}}],"responses":{"200":{"description":"Promotions retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"components":{"schemas":{"PaginationMeta":{"type":"object","properties":{"current_page":{"type":"integer","description":"Current page number"},"last_page":{"type":"integer","description":"Last page number"},"per_page":{"type":"integer","description":"Number of items per page"},"total":{"type":"integer","description":"Total number of items"},"data":{"type":"array","description":"Collection of items for the current page","items":{"type":"object"}}}}}}}
```

## Get promotion details

> Retrieve details of a specific promotion

```json
{"openapi":"3.0.0","info":{"title":"Terragon API Document","version":"1.0.0"},"tags":[{"name":"Bonus","description":"Player bonuses and promotions"}],"servers":[{"url":"https://api.terragon.io/player/api","description":"Staging server"}],"paths":{"/v1/promotions/{slug}":{"get":{"tags":["Bonus"],"summary":"Get promotion details","description":"Retrieve details of a specific promotion","operationId":"getPromotionDetails","parameters":[{"name":"slug","in":"path","required":true,"description":"Promotion slug","schema":{"type":"string"}}],"responses":{"200":{"description":"Promotion details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Promotion"}}}},"404":{"description":"Promotion not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Promotion":{"type":"object","properties":{"id":{"type":"integer","description":"Promotion ID"},"name":{"type":"string","description":"Promotion name"},"slug":{"type":"string","description":"Promotion slug"},"description":{"type":"string","description":"Promotion description"},"short_description":{"type":"string","description":"Short description"},"image_url":{"type":"string","description":"Promotion image URL"},"banner_url":{"type":"string","description":"Promotion banner URL"},"start_date":{"type":"string","format":"date-time","description":"Promotion start date"},"end_date":{"type":"string","format":"date-time","description":"Promotion end date"},"is_active":{"type":"boolean","description":"Whether the promotion is active"},"bonus":{"$ref":"#/components/schemas/Bonus"},"created_at":{"type":"string","format":"date-time","description":"Promotion creation timestamp"}}},"Bonus":{"type":"object","properties":{"id":{"type":"integer","description":"Bonus ID"},"name":{"type":"string","description":"Bonus name"},"description":{"type":"string","description":"Bonus description"},"type":{"type":"string","enum":["deposit","no_deposit","free_spin"],"description":"Bonus type"},"min_deposit":{"type":"number","format":"float","description":"Minimum deposit required"},"max_amount":{"type":"number","format":"float","description":"Maximum bonus amount"},"wagering_multiplier":{"type":"number","format":"float","description":"Wagering requirement multiplier"},"validity_days":{"type":"integer","description":"Validity period in days"},"is_active":{"type":"boolean","description":"Whether the bonus is active"}}},"Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}}}}}}
```