Skip to content
Promotions / Free spins
Promotions
On this page

Free spins

Grant a player free spins on games of one provider. The player finds them in the game.

Grant free spins

POST

/v1/free-spins

Grant free spins. Idempotent on reference.

SignedSandboxProduction
FieldTypeRequiredDescription
player_idstringyesYour player reference.
currencystringyesISO 4217.
game_idsstring[]yes1 to 50 catalogue game IDs from GET /v1/games, all of one provider.
quantityintegeryes1..10000 spins.
bet_amountstring (money)yesStake of one spin. Pick it from GET /v1/free-spins/bet-options.Example: "0.20"
valid_untilstring (date-time)yesIn the future, at most 90 days away.
referencestringyesYour 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.
brandobjectnoWhich 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.codestringnoRequired 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.domainstringnoThe brand site as a bare host name, with no scheme, port or path.Example: casino.example
buy_in_idstringnoA 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"
Request
{
  "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" }
}
Response 200
{
  "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

errorHTTPRetryMeaning
VALIDATION_FAILED422noA 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_REFUSED409noThe game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.
GAME_UNAVAILABLE409noThe 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_id is what your wallet sees on the bets and wins of the series. It is your reference when 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_spins on each game of GET /v1/games says 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 bet and win carrying free_spins_id. Take nothing for the bet; book the win as bonus money.

Accepted stakes

GET

/v1/free-spins/bet-options?game_id={id}&currency={code}&brand={code}&player_id={id}

Stakes the game provider accepts for a grant on this game, lowest first.

SignedSandboxProduction

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.

Response 200
{ "game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10", "currency": "EUR", "amounts": ["0.10", "0.20", "0.50", "1.00"] }

Possible errors

errorHTTPRetryMeaning
VALIDATION_FAILED422noA 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_REFUSED409noThe game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.
GAME_UNAVAILABLE409noThe 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.

GET

/v1/free-spins/buy-ins?game_id={id}&currency={code}

Bought features a free spin of this game may open with.

SignedSandboxProduction

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.

Response 200
{ "game_id": "6ddd5f30-0b1c-4c52-9f3e-2a7c1b8e4d10", "currency": "EUR", "buy_ins": [{ "id": "BUYIN_BONUS_ICON_9", "price": "111" }] }

Possible errors

errorHTTPRetryMeaning
VALIDATION_FAILED422noA 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_REFUSED409noThe game provider does not take grants, refused this one, or the games cannot be granted together. message carries the reason.
GAME_UNAVAILABLE409noThe 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.

GET

/v1/free-spins/providers

The providers whose games take free-spin grants, sorted.

SignedSandboxProduction
Response 200
{ "provider_codes": ["evoplay", "pragmaticplay"] }

Read a grant

GET

/v1/free-spins/{id}

The grant as it stands; status becomes finished when a provider that settles in one call has paid it.

SignedSandboxProduction

Possible errors

errorHTTPRetryMeaning
NOT_FOUND404noNo 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.

GET

/v1/free-spins?reference={reference}

Find a grant by your reference. There is no list call.

SignedSandboxProduction

Possible errors

errorHTTPRetryMeaning
NOT_FOUND404noNo 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_FAILED422noA 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

POST

/v1/free-spins/{id}/cancel

Withdraw an active series. Idempotent: a repeat answers the same grant.

SignedSandboxProduction

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

errorHTTPRetryMeaning
NOT_FOUND404noNo 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_REFUSED409noThe 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.