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.
{
"player_id": "p_82731",
"game_ids": ["prg_sweet_bonanza"],
"rounds": 20,
"bet_value": "0.20",
"currency": "EUR",
"expires_at": "2026-11-17T23:59:59Z"
}Free spins through a game aggregator
- 01
Your bonus engine decides
Eligibility, wagering rules and campaigns stay in your platform.
- 02
Award the rounds
One call names the player, eligible games, round count, bet value and expiry.
- 03
The studio runs the rounds
The player sees the free rounds when they open an eligible game.
- 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.
| Field | What you set | If it is wrong |
|---|---|---|
| Player | The id in your accounts | Rounds open on a different account |
| Games | Only titles the catalogue flags as eligible for external awards | The studio never shows the rounds |
| Rounds and bet value | A count and a stake inside that studio's limits | The campaign stakes a size you did not approve |
| Expiry | A timestamp the studio accepts | Rounds linger, or they disappear before the player opens the game |
| Currency | The currency of that player's wallet | A 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.
| Line | What it is | Where it comes from |
|---|---|---|
| Awards issued | Players multiplied by rounds, from your send log | Your bonus engine's award records |
| Rounds played | What the studio actually executed | The studio's promotional report |
| Flagged credits | Free-round winnings by amount and player | Wallet credit lines carrying the free-round flag |
| Promotional cost | The credits in full, because no stake was taken | Your ledger, kept apart from cash stake |
| Unplayed rounds | Issued minus played; expired rounds belong here | The 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.