Turnkeyxgaming

Feature · Free spins

Free spins API across studios

Free spins are the most common casino promotion and one of the hardest to run across many studios, because each studio implements free rounds its own way. The casino free spins API gives you one call to award them, whichever studio made the game.

POST /bonuses/free-rounds
{
  "player_id": "p_82731",
  "game_ids": ["prg_sweet_bonanza"],
  "rounds": 20,
  "bet_value": "0.20",
  "currency": "EUR",
  "expires_at": "2026-11-17T23:59:59Z"
}
Illustrative request. Supported studios and fields are listed in the docs pack.

Free spins through a game aggregator

  1. 01

    Your bonus engine decides

    Eligibility, wagering rules and campaigns stay in your platform.

  2. 02

    Award the rounds

    One call names the player, eligible games, round count, bet value and expiry.

  3. 03

    The studio runs the rounds

    The player sees the free rounds when they open an eligible game.

  4. 04

    Winnings settle

    Free spin winnings arrive as credits, flagged so your bonus engine can apply wagering.

Free spins API integration notes

Not every studio supports externally awarded free rounds, and those that do apply different limits on bet values and expiry. The slots free spins API exposes which games accept awards, so campaigns can only target eligible titles. Free spins API integration therefore starts with catalogue filtering, not with the award call.

Keep the accounting clean. Where the studio awards the rounds without a player debit, GGR on those rounds is negative by the amount won; some studios book a zero-value stake instead, so confirm which model applies to each title on your studio list before finance publishes a number. Mark bonus-funded wins in your ledger so finance sees promotional cost apart from game performance.

Fields the free-round award has to get right

The sample request on this page is illustrative. Studio limits on stake and expiry are in the docs pack, and they differ by title.

FieldWhat you setIf it is wrong
PlayerThe id in your accountsRounds open on a different account
GamesOnly titles the catalogue flags as eligible for external awardsThe studio never shows the rounds
Rounds and bet valueA count and a stake inside that studio's limitsThe campaign stakes a size you did not approve
ExpiryA timestamp the studio acceptsRounds linger, or they disappear before the player opens the game
CurrencyThe currency of that player's walletA win posts in a unit the ledger does not hold

Two campaigns on the same slot

One player can hold two awards on one game. The credit that returns is flagged as free-round winnings, and your bonus engine still has to know which campaign it belongs to. Keep a campaign reference on your side against the award you sent. Wagering multiples, contribution and cash-out caps stay in that engine. The studio plays the rounds. Free-round winnings describes how to read the flagged credit, and the daily GGR file is where finance keeps promotional cost apart from cash stake.

A free-round win is promotional cost

On a studio that awards rounds without a player debit there is no cash debit on the round, and a win makes GGR negative by the amount credited. Confirm that model per studio, because some book a zero-value stake instead. Mark the credit before it is mixed with ordinary spins, or the studio will look like it malfunctioned on a day that was actually a campaign.

Free rounds and bonus credit are different instruments

Both are called 'free money' in campaign meetings and neither behaves like the other on the wallet. Choosing the wrong one produces an accounting mess rather than a promotion.

Free rounds, executed by the studio

  • The studio runs the spins on the named game, at the bet value you set
  • No debit touches the wallet on any of the rounds
  • Each win returns as a credit flagged as free-round winnings
  • Expiry travels with the award; a round that expires unused is neither stake nor win

Bonus credit, controlled by you

  • Money your platform places into a bonus balance you own
  • The player spends it on any game your contribution table allows
  • Wagering is tracked by your engine across every round, not by the studio
  • Weighting decides how fast it clears; see wagering contribution

Where an award shows up, and where it does not

After the award call returns an acceptance, most studios go quiet until the player opens an eligible game. There is no callback announcing 'rounds played' on the usual integration, so visibility comes from reconciliation rather than events. Three numbers have to agree once the campaign window closes: rounds awarded on your send log, rounds played on the studio's promotional report, and flagged credits on the wallet. When the three disagree, the gap is the investigation — and it is usually an expiry the player never saw or a game the campaign never reached.

The silent failure is targeting. Under most studio award routines, an award sent against a title that does not support external awards is accepted and then never rendered, which reads as a sent campaign and plays as nothing. That behaviour is provider-specific, so confirm it per studio in writing rather than assuming it. The catalogue flag, not the acceptance response, is what proves the client can show the rounds. How to read the flagged credit when it does arrive is covered under free-round winnings.

Accounting

The reconciliation to run after every campaign

Finance should be able to close a campaign from five lines. If a line cannot be produced, the campaign records are missing the field that produces it.

LineWhat it isWhere it comes from
Awards issuedPlayers multiplied by rounds, from your send logYour bonus engine's award records
Rounds playedWhat the studio actually executedThe studio's promotional report
Flagged creditsFree-round winnings by amount and playerWallet credit lines carrying the free-round flag
Promotional costThe credits in full, because no stake was takenYour ledger, kept apart from cash stake
Unplayed roundsIssued minus played; expired rounds belong hereThe difference, reconciled at expiry

FAQ

Questions operators ask

Can I award free spins on any slot?

Only on games whose studio supports external free-round awards. The catalogue flags them.

Where is the wagering requirement applied?

In your bonus engine. The slots free spins API credits a flagged win. It does not apply your playthrough multiple, your game weights or your maximum cash-out.

What happens when the studio rejects the bet value?

The studio rejects the award, so the rounds never appear in the game and the player sees no free spins. Allowed stakes and expiry differ by studio. Filter to titles the catalogue flags as accepting external awards, and to an allowed bet value, before you announce the campaign. Reconcile on rounds actually played, not on the accepted request.

Do free rounds ever produce a wallet debit?

Under the standard external-award contract, no: the studio runs the rounds without a stake, so the only wallet movement on the awarded game is the flagged credit on a win. Two exceptions are worth checking in your own agreement: a campaign that also lets the player stake cash on the same title, and any studio that bills a fee for the award rather than recovering it commercially. Both should appear as separate ledger lines, never folded into the free-round result.

How do I prove an award actually reached the player?

With two records together: the acceptance your call returned, and rounds played on the studio's report. Acceptance alone is not delivery — a campaign aimed at a title without the external-award flag stays invisible. Reconcile the counts once the window closes.

Can a free-round win be paid as bonus money instead of cash?

That is your campaign's decision, made in the bonus engine when the flagged credit lands. The studio hands back a win; what it becomes — cash, a bonus balance with wagering, or a capped amount — follows your published terms. Change the treatment between campaigns and say so in the terms, not in support replies.

Keep reading

Related pages

  • Product · SlotsSlotsVideo slots, jackpot slots and classic reels from many studios share one integration, one wallet and one daily GGR file.Read
  • Solution · PlatformCasino platformPlayer accounts, a back office, a bonus engine and multi-brand support, wired to the game aggregator and the shared wallet.Read
  • Studio · Pragmatic PlayPragmatic PlayPragmatic Play slots such as Gates of Olympus and Sweet Bonanza, plus the studio's own live casino and bingo, on one wallet.Read
  • Product · WalletWalletBalance, bet, win and rollback on one seamless wallet: idempotent transaction ids shared by casino games and sportsbook alike.Read

Get a written quote and sandbox access

Tell us your licence, target markets and products. You get the GGR rate in writing, the studio list for your markets and sandbox credentials.

Telegram @turnkeyxhub WhatsApp Email Contact form