Issue free rounds

POST

/free-rounds

• Production

Issue free rounds (free spins) to a player on one or more games. count is per game — games: [A, B] with count: 10 issues 10 rounds on each (20 total). Not tied to a session; every game must support free rounds and passes the same jurisdiction check as a launch.

Requires the write scope and an Idempotency-Key header (same key + same body replays the cached result; same key + different body → 409). Free rounds must be enabled for the provider before issuance succeeds.

Authorizations

• bearerAuth

Parameters

Header Parameters

Idempotency-Key

required

string

<= 128 characters /^[A-Za-z0-9_-]+$/

Unique key for idempotent retry semantics. Retries within 24 hours return the cached response. Same key with a different body returns 409 Conflict.

Request Body^required

object

provider_code

required

string

>= 1 characters <= 64 characters

truelabs

player_id

required

string

>= 1 characters <= 128 characters

games

required

Catalog game UUIDs (from GET /v1/games). Every game must support free rounds.

Array<string>

>= 1 items <= 200 items

count

required

Rounds per game (not total). games:[A,B] with count:10 issues 20 total.

integer

>= 1

currency

required

string

>= 3 characters <= 10 characters

EUR

country

required

ISO 3166-1 alpha-2. Checked against jurisdiction rules at issue time.

string

>= 2 characters <= 2 characters

coin_level

Stake level (provider-dependent). Provide exactly one of coin_level / bet_amount.

integer

>= 1 <= 24

bet_amount

Stake per round in major units (provider-dependent).

number

> 0

start_at

required

When the rounds become playable.

string format: date-time

end_at

required

When unplayed rounds expire.

string format: date-time

campaign_id

Your campaign reference (optional).

string

<= 128 characters

free_round_kind

The kind of free round; echoed back on the settlement callback.

string

default: voucher

Allowed values: freespin freeticket voucher

sub_operator_ref

Platform accounts only. Which brand’s players receive the grant. Same rules and error codes as sub_operator_ref on POST /v1/sessions; the grant lands on the brand’s identity so settlement routes to the same brand the session did.

Because the grant is keyed on the brand, the same ref must be sent to GET /v1/free-rounds and POST /v1/free-rounds/{grant_id}/cancel to see or cancel it.

string

brand-01

Responses

200

Idempotent replay of a previously issued grant.

object

grant_id

string format: uuid

status

string

Allowed values: active issue_failed

provider_code

string

player_id

string

currency

string

count_per_game

integer

total_rounds

integer

start_at

string format: date-time

end_at

string format: date-time

games

Array<object>

object

game_id

string format: uuid

count

integer

status

Per-game outcome, e.g. active or issue_failed.

string

error

string

nullable

201

Grant issued for all games.

object

grant_id

string format: uuid

status

string

Allowed values: active issue_failed

provider_code

string

player_id

string

currency

string

count_per_game

integer

total_rounds

integer

start_at

string format: date-time

end_at

string format: date-time

games

Array<object>

object

game_id

string format: uuid

count

integer

status

Per-game outcome, e.g. active or issue_failed.

string

error

string

nullable

207

Partially issued — some games failed (see per-game status).

object

grant_id

string format: uuid

status

string

Allowed values: active issue_failed

provider_code

string

player_id

string

currency

string

count_per_game

integer

total_rounds

integer

start_at

string format: date-time

end_at

string format: date-time

games

Array<object>

object

game_id

string format: uuid

count

integer

status

Per-game outcome, e.g. active or issue_failed.

string

error

string

nullable

400

Validation failed, missing Idempotency-Key, or invalid stake.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

401

Missing, invalid, or revoked API key.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

403

Free rounds disabled for the provider, jurisdiction blocked, or player self-excluded.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

409

Idempotency key reused with a different request body.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

422

A game does not support free rounds, or the stake is outside its limits.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

429

Rate limit exceeded; consult Retry-After.

object

error

required

object

code

required

Machine-parseable error code. See https://docs.aggregator.gg/resources/error-codes/.

string

/^E[0-9A-F][0-9]{3}$/

E0001

type

Snake-case mnemonic for the code (e.g. game_blocked_jurisdiction, player_self_excluded). Branch on code; type is for readability.

string

game_blocked_jurisdiction

message

required

string

request_id

Correlation ID for support escalation.

string

details

object

key

additional properties

any

Headers

Retry-After

integer

Seconds to wait before retry.