# Update user spin-wheel information Add, remove or set one trader's available spins, wheel streak or both on one spin-the-wheel game. - Endpoint: `POST https://api.returning.ai/v1/mini-game-logs/update-wheel-info` - Section: Gamification / Streaks and mini games - Authentication: `Authorization: Bearer ` (Community API key) - Permission: `customerSuccess` (Shown in the dashboard as "Customer Success") - Retries: No Idempotency-Key; read state before retrying - Guide: hand-written - Verified: code, 2026-09-27 - Last updated: 26 Sep 2026 - Web page: https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/update-user-spin-wheel-information ## When to use this - Give back a spin a trader lost to a fault on your side, once your team has approved the correction. - Restore a trader's wheel streak after an outage broke it. - Remove spins that were granted by mistake. **Instead:** Use [Get mini-game and streak state](https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/get-mini-game-and-streak-state.md) instead to check a trader's spins and streak before you change anything. **Not repeat-safe:** `add` and `subtract` apply again on every call. After a timeout, read the trader's state and logs before you send the same request. ## Authentication - Header: `Authorization: Bearer ` - Permission: `customerSuccess` Use a Community API key with `customerSuccess`, shown in the dashboard as Customer Success, and keep it on your server. The key decides the community, so `gameId` must be a wheel in that community. ## Behaviour This changes a trader's balance of spins, so agree a correction before you send it. Read the trader's current state and history first, then send one correction and read the state again. Spins you add never expire. When spins are removed, by `subtract` or an `overwrite` below the current count, the spins closest to expiry go first. Adding spins also raises the trader's total of spins earned. Setting the streak also raises the trader's best streak on this wheel when the new value is higher; it never lowers it. When you send both, spins change first and the streak second. Each call adds one `admin-updated` entry to the trader's mini-game logs, attributed to `API Admin`. Two `overwrite` calls for the same trader at the same moment can both add spins, so send corrections one at a time. ## Request ### Headers | Name | Type | Required | Description | | --- | --- | --- | --- | | `Authorization` | `string` | Yes | Community API key with `customerSuccess`. (`Bearer `) | | `Content-Type` | `string` | Yes | Request body format. (`application/json`) | ### Body Send `email`, `gameId`, and at least one pair: `spin_op` with `spin`, `streak_op` with `streak`, or both pairs. The pairs are independent: you can add spins and overwrite the streak in the same call. Values of `0` are allowed, so `overwrite` with `0` clears spins or the streak. The email lookup isn't limited to your community: an email that belongs to someone outside it still updates that person's state on your wheel. Confirm the trader with Get User Data first. | Name | Type | Required | Description | | --- | --- | --- | --- | | `email` | `string` | Yes | The trader's email. Matched without regard to case. (Email format) | | `gameId` | `string` | Yes | ID of a spin-the-wheel game in your community. It isn't returned by Get mini-game and streak state; take it from `miniGameId` in the trader's mini-game logs. (24-character hex ID) | | `spin_op` | `string` | No | How to apply `spin`: `add` gives extra spins, `subtract` removes spins (never below 0), `overwrite` sets the available spins to exactly `spin`. Required with `spin`. (`add`, `subtract` or `overwrite`) | | `spin` | `integer` | No | Number of spins for `spin_op`. Send `spin`, `streak` or both. (Whole number, 0 or more) | | `streak_op` | `string` | No | How to apply `streak`: `add`, `subtract` (never below 0) or `overwrite`. Required with `streak`. (`add`, `subtract` or `overwrite`) | | `streak` | `integer` | No | The streak value for `streak_op`. (Whole number, 0 or more) | ### Example request ```bash curl --request POST \ --url https://api.returning.ai/v1/mini-game-logs/update-wheel-info \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "email": "trader@example.com", "gameId": "66f000000000000000000702", "spin_op": "add", "spin": 1, "streak_op": "overwrite", "streak": 3 }' ``` ## Response A `200` means the changes are saved. `data.spinResult` and `data.streakResult` appear only for what you sent. This endpoint has no top-level `code`; branch on the HTTP status. ### Response fields | Field | Type | Presence | Description | | --- | --- | --- | --- | | `status` | `string` | always | Result of the request. (`success`) | | `message` | `string` | always | Human-readable summary that includes the email. Do not branch on it. | | `data` | `object` | always | What changed. | | `data.miniGameId` | `string` | always | The game you changed. | | `data.gameName` | `string` | always | The game's name. | | `data.spinResult` | `string` | - | Present when you sent `spin`. Says what happened, such as `Added 1 spin(s). 0 -> 1`, `Removed 2 spin(s). 3 -> 1` or `No change needed. Current: 1`. Wording can change; read the new state instead of parsing it. | | `data.streakResult` | `string` | - | Present when you sent `streak`, such as `Streak updated. 0 -> 3`. | ### Example response (200) ```json { "status": "success", "message": "Updated wheel info for trader@example.com", "data": { "miniGameId": "66f000000000000000000702", "gameName": "Daily Spin the Wheel", "spinResult": "Added 1 spin(s). 0 -> 1", "streakResult": "Streak updated. 0 -> 3" } } ``` ## Errors Errors on this endpoint have no machine-readable code; branch on the HTTP status. A key without `customerSuccess` gets `401`, not `403`, with only a `message`. A body without `spin` or `streak`, or with a value but no matching `_op`, returns an HTML `500` page instead of a JSON `400`. ### Fix the request | Status | Code | What to do | | --- | --- | --- | | 400 | - | `email` or `gameId` is missing or malformed, an `_op` isn't `add`, `subtract` or `overwrite`, or a value is negative or not a whole number. `detail` names each field. Nothing changed. | | 401 | - | The key is missing, invalid or expired, it's a personal key, or it lacks `customerSuccess` (`message` is then `Your api key does not have permission to access this action`). Send `Authorization: Bearer ` with a current Community API key, and add Customer Success in Settings > Integration > API Keys. | ### Fix the data | Status | Code | What to do | | --- | --- | --- | | 404 | - | Nothing changed. `message` says which: `User not found with the provided email`, or `Spin wheel game not found for the provided gameId` (the ID isn't a spin-the-wheel game in your community). | ### Do not retry | Status | Code | What to do | | --- | --- | --- | | 500 | - | An HTML error page, not JSON, means the body had neither `spin` nor `streak`, or sent a value without its `_op`. Nothing changed; fix the body. A JSON `500` means the update failed part-way, and the spin change may already be saved. Read the trader's state before you try again. | **Retries:** This endpoint doesn't accept an `Idempotency-Key`. `add` and `subtract` apply again on every call; `overwrite` gives the same result when repeated. After a timeout or a JSON `500`, read the trader's state with Get mini-game and streak state and check the logs before you send it again. Over the [rate limit](https://docs.returning.ai/how-it-works.md#rate-limits), requests return `429`; wait for the window to reset, then retry. ## Next step - [Get mini-game and streak state](https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/get-mini-game-and-streak-state.md): `POST /v1/users/mini-game-streak-stats`. Confirm the trader's new spins and streak. - [Find the correction in the trader's history with List mini-game logs by user email](https://docs.returning.ai/api-reference/gamification-streaks-and-mini-games/list-mini-game-logs-by-user-email.md): `POST /v1/mini-game-logs/by-email`.