> ## Documentation Index
> Fetch the complete documentation index at: https://doc.va777.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Free spin events

> Rules and workflow for giving players free spins as a promotional reward.

Use this feature for promotions: give players free spins as a reward.

> [!NOTE]
>
> **Slot games only.** Contact our AM team for the list of games that support free spins.

## Rules

* You set the **bet** per spin and the **number of free spins**.
* Free spins are bound to the member when they enter the game. The member can leave mid-way and place normal bets; unused spins are kept until the event ends.
* If the member leaves early, unused spins are kept, and an icon reminds them the next time they enter the game.
* During free spins, **free games and feature games can still be triggered**.
* Free spin rewards are **paid directly into the member's wallet**.
* The time from event start to event end must be **31 days or less**.

### Payout limits

You can set a **minimum and maximum payout** per player. With a minimum of 1 and a maximum of 100:

| Member | Total payout over 10 spins | Actual payout | Reason |
| - | - | - | - |
| Member A | 0.5 | 0 | Below the minimum payout of 1 |
| Member B | 180 | 100 | Above the maximum payout of 100 |

## Flowchart

```mermaid theme={null}
flowchart TD
    A["Create free spin event<br/>POST /freespin/create"] --> B["Get eventID"]
    B --> C{"joinOptions"}
    C -->|auto| D["Channel members get a grant<br/>when they enter an eligible game, until the quota is full"]
    C -->|add| E["Grant free spins<br/>POST /freespin/bind"]
    E --> F["Specified members receive a grantID"]
    D --> G["Member enters the game and the free spins are bound"]
    F --> G
    G --> H{"settlePerSpin"}
    H -->|true| I["Pay out on every spin<br/>triggerType = PER_SPIN"]
    H -->|false| J["Settle once all spins are used<br/>triggerType = FINAL_SETTLE"]
    G -.->|Unused at expiry| K["Settle on expiry<br/>triggerType = EXPIRE_SETTLE"]
    I --> L["Apply minimum / maximum payout"]
    J --> L
    K --> L
    L --> M["Payout credited to the member's wallet"]
    M --> N["Reconcile: payouts / bets / report"]
    F -.->|If needed| O["Freeze grants<br/>POST /freespin/freeze"]
    B -.->|If needed| P["Cancel the whole event<br/>POST /freespin/cancel"]
```

## Workflow

1. **Create an event**: Call [Create free spin event](https://doc.va777.net/en/v2/api-reference/freespin/create.md) to get an `eventID`. `joinOptions` controls how members join: `auto` lets every member of the channel join until the quota is full; `add` requires you to choose the members.
2. **Grant to specific members (joinOptions includes add)**: Call [Grant free spins](https://doc.va777.net/en/v2/api-reference/freespin/bind.md) to issue grants to members in one batch.
3. **Manage grants**: Check status with [List free spin grants](https://doc.va777.net/en/v2/api-reference/freespin/grant.md). If needed, freeze grants with [Freeze free spins](https://doc.va777.net/en/v2/api-reference/freespin/freeze.md), or cancel the whole event with [Cancel free spin event](https://doc.va777.net/en/v2/api-reference/freespin/cancel.md).
4. **Reconcile**: Query payouts and bets with [List free spin payouts](https://doc.va777.net/en/v2/api-reference/freespin/withdraw.md), [List free spin bets](https://doc.va777.net/en/v2/api-reference/freespin/list-by-time.md) and [Get free spin report](https://doc.va777.net/en/v2/api-reference/freespin/report.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.