Free spins
Grant a player free spins on games of one provider. The player finds them in the game.
Grant free spins
/v1/free-spins
Grant free spins. Idempotent on reference.
| Field | Type | Required | Description |
|---|---|---|---|
| player_id | string | yes | Your player reference. |
| currency | string | yes | ISO 4217. |
| game_ids | string[] | yes | 1 to 50 catalogue game IDs from GET /v1/games, all of one provider. |
| quantity | integer | yes | 1..10000 spins. |
| bet_amount | string (money) | yes | Stake of one spin. Pick it from GET /v1/free-spins/bet-options.Example: "0.20" |
| valid_until | string (date-time) | yes | In the future, at most 90 days away. |
| reference | string | yes | Your id for the grant, up to 120 characters. A repeat under it answers the first grant; a repeat of a grant that failed places it again. |
| brand | object | no | Which of your brands the player plays on, as in POST /v1/sessions. A game provider that keeps an account per brand places the series under that brand's account, where the game opens. Absent, the brand of the player's latest session is taken, and failing that your own account. |
| brand.code | string | no | Required when brand is sent. The same code as in POST /v1/sessions: 1 to 64 letters, digits, . _ -, starting with a letter or digit.Example: brand-a |
| brand.domain | string | no | The brand site as a bare host name, with no scheme, port or path.Example: casino.example |
| buy_in_id | string | no | A bought feature each spin opens with instead of an ordinary spin, from GET /v1/free-spins/buy-ins. Needs exactly one game in game_ids. The player is not charged its price.Example: "BUYIN_BONUS_ICON_9" |
{
"player_id": "p-1",
"currency": "EUR",
"game_ids": ["6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10"],
"quantity": 10,
"bet_amount": "0.20",
"valid_until": "2026-10-31T00:00:00Z",
"reference": "promo-7",
"brand": { "code": "brand-a", "domain": "casino.example" }
}{
"id": "3333c0de-…",
"free_spins_id": "promo-7",
"status": "active", // pending | active | finished | failed | cancelled
"player_id": "p-1",
"currency": "EUR",
"game_ids": ["vs20fruitsw"], // game provider codes, as the series was placed
"quantity": 10,
"bet_amount": "0.20",
"valid_until": "2026-10-31T00:00:00Z",
"reference": "promo-7",
"created_at": "2026-09-29T12:00:00Z",
"finished_at": null,
"cancelled_at": null,
"win_amount": null, // total paid, where the provider settles the series in one call
"buy_in_id": null // the bought feature each spin opens with, when the grant named one
}Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Also an unknown type, or a cursor that did not come from this listing, on GET /v1/games. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. Also a request the service behind the call refused for a reason of its own: then fields is empty and message says why. |
| FREE_SPINS_REFUSED | 409 | no | The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason. |
| GAME_UNAVAILABLE | 409 | no | The game is not in your window, whether or not it exists. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
Notes
free_spins_idis what your wallet sees on the bets and wins of the series. It is yourreferencewhen that is plain (a letter or digit, then letters, digits,_ . : -, at most 64 characters) and not yet used; otherwise an id of ours.- Games that cannot be granted together answer
FREE_SPINS_REFUSED. Place them as separate grants.free_spinson each game ofGET /v1/gamessays in advance whether it can be granted. pending: accepted, not yet confirmed by the game provider.failed: the game provider refused it.- Your wallet sees the play as
betandwincarryingfree_spins_id. Take nothing for the bet; book the win as bonus money.
Accepted stakes
/v1/free-spins/bet-options?game_id={id}¤cy={code}&brand={code}&player_id={id}
Stakes the game provider accepts for a grant on this game, lowest first.
A provider that keeps an account per brand may accept different stakes on each. Send brand (your brand code, the same as brand.code in POST /v1/sessions) for the brand the grant is for; without it, player_id stands in with the brand of the player's latest session. With neither, the stakes are read under your own account, as for a grant without a brand. Both are optional.
{ "game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10", "currency": "EUR", "amounts": ["0.10", "0.20", "0.50", "1.00"] }Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Also an unknown type, or a cursor that did not come from this listing, on GET /v1/games. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. Also a request the service behind the call refused for a reason of its own: then fields is empty and message says why. |
| FREE_SPINS_REFUSED | 409 | no | The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason. |
| GAME_UNAVAILABLE | 409 | no | The game is not in your window, whether or not it exists. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
/v1/free-spins/buy-ins?game_id={id}¤cy={code}
Bought features a free spin of this game may open with.
id is what a grant names as buy_in_id; price is the feature's cost as a multiple of the spin's stake. An empty list means the game sells none, or its provider does not take them with free spins. Endorphina calls these Bonus Pop.
{ "game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10", "currency": "EUR", "buy_ins": [{ "id": "BUYIN_BONUS_ICON_9", "price": "111" }] }Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Also an unknown type, or a cursor that did not come from this listing, on GET /v1/games. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. Also a request the service behind the call refused for a reason of its own: then fields is empty and message says why. |
| FREE_SPINS_REFUSED | 409 | no | The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason. |
| GAME_UNAVAILABLE | 409 | no | The game is not in your window, whether or not it exists. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
/v1/free-spins/providers
The providers whose games take free-spin grants, sorted.
{ "provider_codes": ["evoplay", "pragmaticplay"] }Read a grant
/v1/free-spins/{id}
The grant as it stands; status becomes finished when a provider that settles in one call has paid it.
Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| NOT_FOUND | 404 | no | No such session, grant, bonus campaign or transaction for your operator, or no such path under /v1. A round we do not know answers an empty list instead. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
/v1/free-spins?reference={reference}
Find a grant by your reference. There is no list call.
Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| NOT_FOUND | 404 | no | No such session, grant, bonus campaign or transaction for your operator, or no such path under /v1. A round we do not know answers an empty list instead. |
| VALIDATION_FAILED | 422 | no | A field is missing, out of range or of the wrong JSON type, or the body is not valid JSON. Also an unknown type, or a cursor that did not come from this listing, on GET /v1/games. Every broken field is listed in fields with the rule it broke; "body" when the JSON does not parse. Also a request the service behind the call refused for a reason of its own: then fields is empty and message says why. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
Cancel a grant
/v1/free-spins/{id}/cancel
Withdraw an active series. Idempotent: a repeat answers the same grant.
Spins already played stay played and what was won stays won. The answer is the grant with status: "cancelled". A grant that is pending, finished or failed cannot be cancelled and answers FREE_SPINS_REFUSED.
Possible errors
| error | HTTP | Retry | Meaning |
|---|---|---|---|
| NOT_FOUND | 404 | no | No such session, grant, bonus campaign or transaction for your operator, or no such path under /v1. A round we do not know answers an empty list instead. |
| FREE_SPINS_REFUSED | 409 | no | The game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason. |
Every endpoint can also answer UNAUTHORIZED, ADDRESS_NOT_ALLOWED, RATE_LIMITED and UPSTREAM_UNAVAILABLE. See the Error reference.
