The Template routes every currency change through CurrencyService and every purchase grant through MonetizationService. The client asks for an action or opens a purchase prompt; the server chooses its price, verifies eligibility and applies the reward. The currency and purchase services are always on. Codes and leaderboards have optional feature switches.
Changing a currency balance
Currency definitions live in src/core/shared/Config/Currencies.luau: each id has its display name, HUD order, symbol, starting amount, hard cap and optional icon. A game adds its own in Config/Overrides/Currencies.luau (an entry per new id, every field written; game code casts the id, which the Template's CurrencyId type does not know). Balances live in per-slot PlayerData.currencies. The HUD reads the synced balances and sorts rows by config order; game code never writes those balances directly.
- getBalance and canAfford
getBalance(player, currencyId)returns the current balance, or nil while data is not loaded.canAffordchecks the current balance without yielding.- add and spend
Both return a
Resultwith the new balance. Amounts must be non-negative integers; unknown ids refuseunknown_currency, invalid amountsinvalid_amount, and a spend the balance cannot coverinsufficient_funds.addclamps to the cap; a positive grant that would add nothing refusesat_cap.- set
Support and admin tooling can overwrite a balance, clamped to its cap. Ordinary gameplay uses
add,spendorexchangeso the intended transaction stays explicit.- exchange
exchange(player, reason, creditReason, change)applies the owning save change and its signed currency deltas in oneDataService.update, or nothing. Negative deltas spend underreason; positive ones are credited undercreditReason:refund:<domain>when they return an earlier spend (quests and the economy check ignore those), the earning's own reason otherwise. A game's sale can spend the sold items and creditsell:<what>in the same write. Credits clamp at the cap, unless the change returnswhole = true: then every credit is paid in full or the whole exchange is refusedat_cap, never part-paid.
A shop purchase is one exchange: it charges the price and raises the level in one write (a level already at its last is never paid for). A quest or season pass tier claim is one RewardService.grant that records the claim and pays the whole reward together, so a reward that does not fit is refused with nothing written and stays claimable.
Every mutation needs a specific reason such as shop:sword or quest:daily. It reaches analytics and CurrencyService.changed, so the anti-cheat can attribute unusual gains. iap: belongs to real product grants, admin: to staff changes, and refund: to a return of an earlier spend. Gameplay must not borrow those prefixes to avoid checks.
One reward shape
Everything the Template gives a player is written the same way, in every config that gives one, and reaches the save through one service:
{ kind = "currency", id = "coins", amount = 100 } -- Config/Currencies{ kind = "item", id = "potion", amount = 3 } -- Config/Inventory{ kind = "boost", id = "doubleCoins", amount = 1 } -- Config/Boosts{ kind = "title", id = "founder" } -- Config/Titles{ currency = "coins", amount = 100 } -- shorthand for kind currencyA config field that takes a reward takes one reward or a list. The shorthand is the shape every config and saved claim had before there were kinds, and stays valid, so old overrides and saved claims need no change. Rewards are configured in Config/Quests, Config/DailyRewards, Config/Playtime, Config/SeasonPass (a tier's free and paid), Config/Referrals (welcome, perFriend), Config/Community.groupReward, Config/Ads (a placement's reward), the server's Config/Codes, and Config/Monetization (a product's or pass's grants.rewards). The Premium bonus and a subscription's period grant stay currency amounts and are paid through the same path. An item, boost or title reward needs its feature (inventory, boosts, titles) on.
RewardService.grant(player, reason, rewards, change?) is one DataService.update (through CurrencyService.exchange, so currency analytics and CurrencyService.changed behave as for any credit). In that write it applies the caller's own record (change: a quest marked claimed, a claim's receipt), every reward (Rules/Grants.apply; items go in under the inventory source rewards), and checks the currency credits whole against each cap. RewardService.fits(player, rewards) runs the same rules without writing. Any refusal leaves the save untouched:
| Refusal | When |
|---|---|
at_cap | a currency credit would pass Config/Currencies.<id>.max |
inventory_full | no free space (Config/Inventory.capacity) for a new stack |
stack_full | the stack would pass the item's maximumStack |
boost_full | the boost's stock would pass Config/Boosts.maxOwned |
switched_off | the kind's feature is off |
unknown_reward | the kind or id is not in the config (a retired item, a typo) |
invalid_reward | the amount is not a whole number above 0 |
A title the save already keeps is skipped, not refused, so the rest of the list is still paid. Windows and notices name a reward with Util/RewardLabel.text ("1,500 Coins", "Founder title"), worded by the reward.* keys of Config/Strings; server notices carry it as the {reward} argument. Nothing on the client reaches RewardService. The Template's note is docs/systems/Rewards.md.
Adding a developer product
Declare the product
Add a key to the game's
Config/Overrides/Monetizationwithid = 0, a display name, a description and apricein whole Robux;falseremoves a Template example.lune run products -- synccreates it in the experience through Open Cloud and writes its id into the overrides (--dry-runshows the plan first). It adopts one that already exists under the same name, and keeps name, description and price in step on every run. It needsROBLOX_API_KEYwith the Game Passes and Developer Products APIs (game-pass:read/write,developer-product:read/write), both in beta at Roblox. It refuses two products of one name and two entries on one id, and skips and lists a product only a switched-off feature sells (a boost's, a gift's, an ad placement's, the season pass's paid track). Game passes work the same way. A zero id means not created yet. Product and pass keys are plain strings, so a game's own keys need no cast. Use the Template'smonetizationskill and its security review procedure.Say what it grants
A product that gives currency, items, boosts or titles needs no handler: set
grants = { rewards = ... }on it, andMonetizationServicegrants them throughRewardService.grant(reasoniap:<key>) where a handler would run, with the same receipt checks, policy and confirmed save. Anything else registers a handler in the owning service'sinit()withMonetizationService.registerProduct(key, handler); a registered handler wins overgrants. Exactly one handler is allowed per key (a rewarded ad placement's product already hasRewardedAdService's). Return true only when the reward really applies. Setstore = <order>to list it in the shop window's Store section.Prompt from the client
Use
MonetizationController.promptProduct(key). Only that controller uses clientMarketplaceService; onlyMonetizationServiceuses it on the server. A closed client prompt is feedback, not proof that a reward should be granted.Check the saved grant and the retry
Run the automated verification, then a Studio purchase and rejoin check. The grant and its toast should appear once, and a receipt retry must not grant it again. Real purchase and saved-data behavior needs a person in Studio or a suitable test experience.
When a receipt is answered PurchaseGranted
Roblox calls the server's ProcessReceipt. A missing player, unknown product, unloaded data, missing handler, error or refused reward answers NotProcessedYet so Roblox can retry. A known receipt skips its handler. With save slots, the service also checks for the receipt in the player's other slots.
For a new receipt, the handler applies the reward, then the service records its PurchaseId, product count and purchase-history row. DataService.saveAndConfirm waits up to 15 seconds for a saved profile containing that receipt before the service answers PurchaseGranted. The confirmation concerns Roblox acknowledging the purchase: the in-memory reward has already been applied at this point.
purchases.receipts and purchases.history are bounded by PlayerData.MAX_RECEIPTS and MAX_HISTORY, oldest first when trimmed. Support's Purchases window merges real history across slots, including offline users. A staff grantproduct applies the handler without recording a real purchase or firing productGranted.
Checking and using game passes
MonetizationService.refreshGamepasses verifies configured non-zero ids with Roblox on load. A positive answer records ownership. Removing recorded ownership requires two negative answers five seconds apart; a failed check changes nothing. Checks run one at a time per player. The in-game purchase-finished signal is also verified with UserOwnsGamePassAsync rather than trusted alone.
ownsGamepass(player, key) reads saved server data without yielding. A newly recorded pass fires gamepassGranted; a pass already recorded does not fire again on every join. Listen for one-time effects, and check ownsGamepass when behavior depends on continuing ownership. The client reads synced gamepasses for its Owned label.
A pass's grants are given once per save, the first time the pass is recorded there and counts for the player's region: the save's flag passGranted.<key> is written with the rewards in one write, so a pass removed and recorded again never pays twice, and rewards that did not fit are tried again at the next check (every join).
Staff grantpass and revokepass change the save for testing or support. They do not alter Roblox ownership, so the next ownership refresh can restore a genuinely owned pass.
The Robux store
The shop window lists every product and pass with store = <order> in Config/Monetization, lowest first, below the upgrades. Each row's button is Buy · N Robux, with Roblox's own price for this player (MonetizationController.price, read once with GetProductInfo, so regional pricing shows as Roblox charges it; Buy with no number until Roblox answers or while the id is 0), or a disabled Owned for a pass the player's save holds or was gifted. The price in config is never shown. A row is hidden where the player's region restricts the item or before that is known. The Template's example product and pass (exampleCoins, granted from config, and exampleVip) are listed only while demo is on. A granted product's or pass's toast is purchases.notice.granted.
Testing purchases without charging Robux
promptProduct and promptGamepass open the Template's Test Purchase dialog. The server
verifies both test mode and a sandboxed save, then applies the real handler to the copy. Zero
ids can be tested here. Product and pass signals carry emulated = true; listeners that affect
badges, broadcasts or leaderboards must skip emulated effects.
Experience subscriptions
Roblox experience subscriptions are monthly, auto-renewing purchases created on the Creator Dashboard (Monetization > Subscriptions). SubscriptionService runs them while Config/Features.subscriptions is on; it is off by default. A game declares each one in Config/Overrides/Monetization.luau under subscriptions: the dashboard's EXP- id ("" until it exists), name and description, perks (flags game code asks about), an optional periodGrant (a currency amount per paid period) and an optional chatTag. Keys are plain strings, so a game's own keys need no cast.
- Perks
Game code asks
SubscriptionService.hasPerk(player, perk)orhasSubscription(player, key)where the perk pays, and re-checks onSubscriptionService.changed(player, key, active). Both read server state and never yield.- Status
The server asks Roblox (
GetUserSubscriptionStatusAsync) when the player's data loads, whenPlayers.UserSubscriptionStatusChangedfires, when a subscription prompt closes, and again once the answer is older thansubscriptionChecks.cacheSeconds. Asks are retried with backoff, never run twice at once, and asks Roblox signals are spaced per player. The client sends nothing.- Unknown
No answer, or an answer not shaped as Roblox documents, is
unknown: no perk, tag or grant, asked again afterretrySeconds. It fails closed.- Period grant
Paid only for a cycle that
GetUserSubscriptionPaymentHistoryAsyncmarks Paid and that covers now: never during Roblox's renewal grace period, never for a refunded cycle. The cycle start is written toAccountData.statswith the period's once-per-account claim (ClaimService, reasonsubscription:<key>), paid into the slot once the account save is confirmed, so it pays once per account per cycle across rejoins, servers and save slots.registerPeriodGrant(key, handler)adds items or anything else as the claim is paid; the handler must not yield.- Selling
MonetizationController.promptSubscription(key)opens Roblox's prompt; the shop window lists each subscription with Subscribe or Active. Both are hidden where Roblox'sIsEligibleToPurchaseSubscriptionpolicy is false or not known yet (thesubscriptionsgate). A subscriber's benefits never depend on that gate.
MonetizationService remains the only server module that calls MarketplaceService; it makes the subscription calls for SubscriptionService. It is a folder module (init with ProcessReceipt and the public API, beside Products, Gamepasses and Gifts); callers require MonetizationService only. The full rules are in the Subscriptions section of docs/systems/Monetization.md.
Rewarded video ads
RewardedAdService runs rewarded video ads while Config/Features.rewardedAds is on; it is off by default. A game names each placement in Config/Ads: a developer product, a fixed reward (one reward or a list of any kind, never random, never Robux, granted whole by RewardService), a dailyCap per player and an optional placementId, with a shared cooldownSeconds. Where Roblox has an ad for the player (GetAdAvailabilityNowAsync, asked on the client when the shop opens) and the regional ads gate allows it, the shop window shows a Watch ad row per placement with the views left today.
The player starts the ad. ads.requestShow checks the placement, its product id, the ads gate, the daily cap, one ad at a time and the cooldown, then calls ShowRewardedVideoAdAsync. Its result never grants: the reward arrives as a receipt through ProcessReceipt (channel AdReward), handled by the placement's product handler, which also counts the day's view in AccountData.stats. Roblox decides who is eligible (13 and over, eligible device and experience); the publisher must be 13+ and ID-verified and the experience public with about 2,000 monthly visitors.
Regional policy gates
RegionPolicyService is the only caller of Roblox's PolicyService. It reads every player's policy on join (again in the background after a failed read), and a product, pass or feature names the gate it depends on. Each gate is allowed, restricted or unknown; unknown sells nothing, without telling the player their region forbids it.
- paidRandomItems
Anything bought with Robux whose outcome is random (eggs, crates, spins), and a game's own random reward bought with a currency that can be bought with Robux. Set
policy = "paidRandomItems"on the product; a restricted player is not offered it and the server refuses its receipt. Show the odds as numbers summing to 100% in a labelled Info or Details pop-up before purchase, and never make it giftable.- paidItemTrading, ads, subscriptions
Trading items bought with Robux or currency, showing rewarded ads, and selling experience subscriptions (a subscriber's benefits never depend on it).
- contentSharing
Sharing content a player made that others can see (
IsContentSharingAllowed, by age and region): the capture feature offers Roblox's save prompt instead of the share prompt where it is not allowed or not read yet, and a game's own signs, builds or posts use the same gate.- External links
Not a gate: the Community Standards allow no link or handle inside an experience, only Social Links on its page (
Config/Game.experience.socialLinks).RegionPolicyService.allowsLinkis always false, because Roblox always answers the legacy list empty.
Redeem codes apply once per account
CodeService reads unpublished codes from server-only src/core/server/Config/Codes.luau, with the game's own in Config/Overrides/Codes.luau merged over them. The Template's WELCOME and BLOCKOUT are demo examples that stay live under demo = false: a game removes them with codes = { WELCOME = false, BLOCKOUT = false } in src/core/server/Config/Overrides/Codes.luau before its first public build. Matching ignores whitespace and case. Dates are UTC, with start included and end excluded; an unparseable or future start answers like an unknown code. Eligibility can require Player.AccountAge in days.
The client sends only code text through codes.requestRedeem. The guard accepts up to 64 UTF-8 bytes; the service matches at most 32 characters. Its per-user attempt bucket has capacity five and refills one token every ten seconds, including wrong attempts. The record is in AccountData.codes and the rewards go into the active slot, so changing slots does not make a used code available again.
The code and its rewards are one once-per-account claim through ClaimService (Data and saving): the code and the claim are written to the account together, and the rewards are paid into the slot with a claim-<id> receipt only once a confirmed account save holds them. A crash at any point pays the code exactly once; a player who leaves first is paid on their next visit, in whichever slot. If the whole reward does not fit (RewardService.fits: a currency cap, a full inventory and the rest), the code is refused and stays unused; while 50 claims already wait on the account it is refused busy.
Features.codes disables the service, window, menu button and its commands. New or changed code config takes effect in new server builds; an old server can still answer unknown until migrated. Keep published config keys stable, because renaming a key lets every account redeem that new key again.
Ranking values larger than ordinary numbers
LeaderboardService supports all-time, daily, weekly and monthly boards through DataService ordered-store methods. Sources can be currency, a numeric stats key, or a custom server-submitted score. Clients never submit a score. Util/BigNum supports arithmetic and display past ordinary Luau number limits; a BigNum uses a custom board.
Rules/Leaderboards.encode packs exponent and significant digits into a safe sortable integer: whole scores below 10^12 are exact, larger values keep 12 significant digits, and scores at or beyond 10^8999 share the top key. This encoding is a storage format; changing it needs a new store prefix. Boards rank the latest written value, so a best-ever board needs the game to save its best-ever stat.
- Periods and saves
Each board and period has its own ordered store. Weekly periods start Monday at 00:00 UTC. Entries are per user, not per slot: playing a weaker slot can lower the user's ranking, including on an all-time board.
- Updates and sandboxing
Scores are written on the first timer flush of a visit, then when changed and on unload. Test-mode scores never reach global boards: entering test mode writes the real save's scores (read through
DataService.onReal). Read and write intervals live inConfig/Leaderboardsand share the DataStore budget with other systems.- The player list's stats
Not a leaderboard:
Config/PlayerList.statsnames the currencies, saved stats or custom values shown asleaderstats, written byPlayerListServiceas text (1e20 reads "100Qi") at most once perupdateSeconds(1) andmaxRowsPerSecond(100) rows a second across the server. Test-mode players' values stay at the real save's. Renaming or removing a currency means updatingConfig/LeaderboardsandConfig/PlayerListtogether; their config specs fail otherwise. See the Player list entry in the systems catalogue.- World and window displays
Tag a part
Leaderboardand give it aBoardattribute.WorldLeaderboardsdraws that board; the Top window lists every configured board.leaderboards.requestMinereturns only the caller's score and a bounded rank lookup, with a cache and a shared read allowance.- Time trials and removals
ascendingranks low scores first andformat = "duration"displays milliseconds as a stopwatch; game code submits the times to acustomboard.lbforgetclears a user's entries in current periods and bounded past periods; a different server can write the user again, so leaderboard removal alone is not a ban.
Support grants
grant <user> <kind> <id> [amount] (developers) gives one reward of any kind to any account, online or not. It is checked against the config and the switches, then sent as a supportGrant account message; the server holding the account (now, or on the player's next join) turns it into a once-per-account claim of kind support, paid exactly once into the slot being played, with a notice to the player. For players in the server, give and giveitem are immediate.
How economy spikes are checked
The anti-cheat observes actual positive currency deltas and compares each configured currency with its gain ceiling over 60 seconds. The default map is empty. Set ceilings from the game's expected rates, including legitimate rewards; the check excludes iap:, admin: and refund: reasons. See Every detection.
The Template vault's source notes are Currency.md, Rewards.md, Monetization.md, Shop.md, Rewarded Ads.md, Regional Policy.md, Leaderboards.md and Codes.md under docs/systems/, and the launch checklist in docs/engineering/Roblox Platform Rules.md. Use the systems catalogue to find shop, quests, daily rewards and inventory.
Updated