# Bonus History

Lists the bonuses you gave with [Create Bonus](https://my.nexusggr.com/app/docs/integration/bonus-api/create-bonus), newest first, with what each has paid and what came back to your agent balance. Filter by user, by `bonus_id`, or by when the bonuses were created.

A bonus still being created is not listed, and neither is one whose `bonus_create` failed.

### Endpoint

```
POST https://api.nexusggr.com
```

**Content-Type:** `application/json`

### Request

**Method:** `bonus_history`

```json
{
    "method": "bonus_history",
    "agent_code": "your_agent_code",
    "agent_token": "your_agent_token",
    "user_code": "test",
    "start": "2026-10-01T00:00:00Z",
    "end": "2026-10-15T23:59:59Z",
    "page": 0,
    "perPage": 100
}
```

| Field         | Type     | Required | Description                                                                    |
| ------------- | -------- | -------- | ------------------------------------------------------------------------------ |
| `method`      | string   | Yes      | Must be `bonus_history`                                                        |
| `agent_code`  | string   | Yes      | Your agent code                                                                |
| `agent_token` | string   | Yes      | Your agent API token                                                           |
| `user_code`   | string   | No       | Only this user's bonuses                                                       |
| `bonus_id`    | string   | No       | Only the bonus with this `bonus_id`                                            |
| `start`       | datetime | No       | Only bonuses created at or after this time, for example `2026-10-01T00:00:00Z` |
| `end`         | datetime | No       | Only bonuses created at or before this time                                    |
| `page`        | integer  | Yes      | Page number, from `0`                                                          |
| `perPage`     | integer  | Yes      | Bonuses per page, `1` – `1000`                                                 |

Give `start` and `end` in ISO 8601 with a time zone (`Z` for UTC). Leave out any filter you do not need. With none, every bonus of your agent is listed.

### Response

#### Success

```json
{
    "status": 1,
    "code": 7777777,
    "msg": "SUCCESS",
    "total_count": 1,
    "page": 0,
    "perPage": 100,
    "bonuses": [
        {
            "bonus_id": "bonus_777",
            "user_code": "test",
            "provider_code": "PRAGMATIC",
            "game_code": "vs20doghouse",
            "max_bet": 2000,
            "amount": 50000,
            "total_win": 46200,
            "refund": 3800,
            "status": "finished",
            "created_at": "2026-10-14T09:12:30.000Z",
            "updated_at": "2026-10-14T09:20:05.000Z"
        }
    ]
}
```

| Field           | Type    | Description                                                                                   |
| --------------- | ------- | --------------------------------------------------------------------------------------------- |
| `total_count`   | integer | Bonuses that match the filters, on all pages                                                  |
| `page`          | integer | The `page` you sent                                                                           |
| `perPage`       | integer | The `perPage` you sent                                                                        |
| `bonuses`       | array   | The bonuses on this page, newest first                                                        |
| `bonus_id`      | string  | The `bonus_id` sent in `bonus_create`                                                         |
| `user_code`     | string  | The user the bonus was given to                                                               |
| `provider_code` | string  | Game provider code                                                                            |
| `game_code`     | string  | The game the bonus was given on                                                               |
| `max_bet`       | integer | The `max_bet` sent in `bonus_create`                                                          |
| `amount`        | number  | The `amount` sent in `bonus_create`, taken from your agent balance when the bonus was created |
| `total_win`     | number  | What the bonus has paid the user so far                                                       |
| `refund`        | number  | What came back to your agent balance. `0` until the bonus ends or is canceled                 |
| `status`        | string  | Where the bonus stands (table below)                                                          |
| `created_at`    | string  | When the bonus was created (UTC)                                                              |
| `updated_at`    | string  | When the bonus last changed (UTC)                                                             |

| `status`    | Description                                                               |
| ----------- | ------------------------------------------------------------------------- |
| `waiting`   | Given, waiting for the user's next round on the game within `max_bet`     |
| `running`   | The user is in the bonus round                                            |
| `finished`  | The bonus round is over. What it did not pay came back                    |
| `refused`   | Its `bonus_create` got no answer, and the game server turned out not to have it. All of `amount` came back |
| `cancelled` | Canceled with [Cancel Bonus](https://my.nexusggr.com/app/docs/integration/bonus-api/cancel-bonus). What it had not paid came back |

#### Failure

```json
{
    "status": 0,
    "code": 7770400,
    "msg": "perPage must be less than or equal to 1000"
}
```

| Code      | Description                                                                         |
| --------- | ----------------------------------------------------------------------------------- |
| `7770400` | A field is invalid, for example `perPage` above `1000` or a `start` that is not a date. `msg` says which |
| `7770405` | `page` or `perPage` is missing                                                      |
| `7770500` | Internal error                                                                      |