references/full.md
# roblox monetization: full reference
> Code examples are illustrative. Adapt them to your project and verify in Studio before production use.
This guide focuses on the server-side correctness of Roblox's purchase APIs. Product catalog setup and current policy requirements change over time; use the linked Creator Hub pages as the authority for eligibility and configuration details.
## 1. Pick the product type
- **Pass:** durable ownership for an experience.
- **Developer Product:** repeatable consumable purchase.
- **Subscription:** recurring benefit with a subscription-specific lifecycle.
- **Private server or paid access:** access configuration rather than an item grant.
- **Creator Rewards and ads:** platform programs with their own eligibility and reporting rules.
Do not model all of these as one "purchase" table. Their ownership, renewal, refund, and retry behavior differ.
## 2. Keep prompting separate from granting
The client owns the presentation and can request a prompt. The server owns the entitlement. A button click or `PromptProductPurchaseFinished` event is never proof of a Developer Product grant.
```luau
-- LocalScript: presentation only
local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")
buyButton.Activated:Connect(function()
MarketplaceService:PromptProductPurchase(Players.LocalPlayer, PRODUCT_ID)
end)
```
For a Game Pass, the server can check ownership before enabling a durable feature.
```luau
local MarketplaceService = game:GetService("MarketplaceService")
local function ownsPass(player: Player, passId: number): boolean
local ok, owns = pcall(function()
return MarketplaceService:UserOwnsGamePassAsync(player.UserId, passId)
end)
return ok and owns == true
end
```
Cache a successful result when appropriate, but provide an invalidation or refresh path for purchases made during the session. Handle API failure as "not confirmed yet," not as a permanent denial or grant.
## 3. Centralize Developer Product receipts
Only one server callback should own `ProcessReceipt`. It must:
1. identify the product and player;
2. determine whether this receipt was already granted;
3. grant through the authoritative data service;
4. record the receipt or transaction id with the grant;
5. return `PurchaseGranted` only after durable success.
`BindReceiptHandler` is a separate API for Robux-transfer sender and receiver
receipts. It does not replace `ProcessReceipt` for Developer Products.
```luau
local MarketplaceService = game:GetService("MarketplaceService")
local Players = game:GetService("Players")
local productGrants = {
[COIN_PRODUCT_ID] = { coins = 500 },
}
MarketplaceService.ProcessReceipt = function(receiptInfo)
local player = Players:GetPlayerByUserId(receiptInfo.PlayerId)
if not player then
return Enum.ProductPurchaseDecision.NotProcessedYet
end
local productGrant = productGrants[receiptInfo.ProductId]
if not productGrant then
warn("Unhandled product", receiptInfo.ProductId)
return Enum.ProductPurchaseDecision.NotProcessedYet
end
local transactionId = tostring(receiptInfo.PurchaseId)
local granted = ReceiptStore:ApplyGrantOnce(
transactionId,
player.UserId,
productGrant
)
if not granted then
return Enum.ProductPurchaseDecision.NotProcessedYet
end
return Enum.ProductPurchaseDecision.PurchaseGranted
end
```
`ApplyGrantOnce` is a project-specific persistence boundary. It must make the
transaction ID and entitlement mutation one durable, idempotent operation, and
must treat an already-granted ID as success. Do not implement it as "grant,
then separately record": a crash or failed record between those operations can
duplicate value on retry.
Cross-owner atomicity: atomic receipt recording for one profile is not an atomic exchange between two profiles; for trading or gifting across profiles, see `roblox-data` full reference, section Cross-owner atomicity limits.
## 3a. Receipt failure tests
For every receipt implementation, force these cases in a test place:
- the player is absent;
- the product is unknown or its handler is missing;
- the grant succeeds but recording the transaction fails;
- the same transaction is delivered twice;
- the server shuts down between grant and acknowledgement.
Receipt failures can be silent in normal play: the player paid and nothing arrived. Treat the durable idempotency record as load-bearing. Do not acknowledge an unknown product or a grant that was not durably recorded, and verify duplicate delivery returns success without granting twice.
## 4. Subscriptions and recurring benefits
Subscriptions need explicit entitlement checks and renewal handling. Keep these separate from one-time Game Pass ownership. A subscription benefit should have:
- a server-side entitlement check;
- a clear expiration or renewal state;
- behavior when the subscription API is unavailable;
- a downgrade path that does not delete unrelated player data;
- UI that describes the actual cadence and benefit.
Use the current subscription documentation for API names and platform eligibility. Do not hard-code assumptions about age, region, or payment availability.
## 5. Private servers and paid access
Private-server prompts, paid access, and item purchases solve different problems. Decide whether the player is buying access, a server instance, or an in-game entitlement. Keep access enforcement on the server and test owners, invited players, and expired or unavailable configurations.
## 6. Policy and presentation
Eligibility-sensitive products may require `PolicyService` checks. Treat a failed policy lookup conservatively for the affected feature, and update the implementation when Roblox changes the documented requirements.
Purchase UI should make the price, cadence, contents, and meaningful restrictions clear. For randomized paid content, the current policy documentation requires outcome and numerical-odds disclosure before purchase, and classifies broad item types as paid random items, including probability modifiers such as luck boosts and pity systems. Do not rely on a color, rarity label, or marketing phrase as a substitute for a required disclosure.
When `ArePaidRandomItemsRestricted` is true for a user, the documentation accepts several treatments: an unpaid earnable path to the item, a pre-determined non-random sequence, guaranteed direct purchase of specific outcomes, hiding the feature, blocking the purchase with a message, or removing the user from the affected part of the game. Blocking is the most disruptive option and the rarest in live games: many large RNG-style experiences keep paid random features available in restricted regions and rely on odds disclosures instead. <!-- temporal: 2026-08, community-reported practice, not documented policy --> Treat the treatments as a menu to present to the user with trade-offs, not a mandate to apply the strictest one. Do not unilaterally region-lock, hide, or remove a monetization feature the user asked for: surface the policy requirement, recommend the least disruptive compliant treatment, and implement what the user decides among the compliant treatments.
Precedence: user approval authorizes an otherwise permitted action; it does not satisfy a mandatory policy and does not turn a failed or unverified gate into PASS. For a restricted user, the restriction itself is mandatory: shipping unchanged or disclosing odds alone does not meet the policy, and a user's "I accept the risk" does not make it compliant. Do not implement a non-compliant choice; restate the compliant alternatives once and proceed with a compliant treatment (or stop that feature and report).
Platform program names and payout rules change. Engagement-Based Payouts is historical/deprecated material, not a current implementation target; consult the current Creator Rewards documentation when working on platform payouts.
## 7. Creator Rewards
Creator Rewards is a platform program rather than an in-experience purchase API. As documented on 2026-07-13, it has two parts:
- **Daily Engagement Rewards:** 5 Robux when an Active Spender spends at least 10 minutes in the experience during a day and the experience is one of the first three they launch that day.
- **Audience Expansion Rewards:** a 35% revenue share on the first $100 of qualifying purchases by an attributed New User or Reactivated User during their first 60 days, subject to the experience's 10-minute, attribution, and average-100-DAU-for-60-days conditions.
Creator Rewards data is surfaced in Creator Dashboard and has a 60-day holding period. There is no server callback that grants the reward to a player and no purchase receipt to process. Do not make Creator Rewards the source of truth for coins, products, or player entitlements.
Treat the program terms as changeable policy. Do not automate engagement, manipulate teleports, encourage alternate accounts, or design an idle loop solely to manufacture reward activity. Review the current eligibility, anti-fraud, and DevEx terms before making a business or content decision.
## 8. Economy design
Monetization changes the economy even when the product is cosmetic:
- faucets increase supply;
- sinks remove supply;
- multipliers change time-to-earn;
- tradeable rewards can create secondary markets;
- limited offers can concentrate demand and support load.
Model the ordinary player path before choosing prices. Track purchases and grants separately so an analytics event cannot become the source of truth for inventory.
## 9. Testing matrix
Test in a non-production place with representative data:
- prompt cancelled;
- ownership API errors;
- unknown product id;
- player leaves before receipt processing;
- receipt callback called twice;
- grant succeeds but receipt recording fails;
- save or shutdown begins during a grant;
- subscription entitlement changes;
- policy lookup denies or cannot determine eligibility.
- Creator Rewards eligibility and dashboard reporting reviewed when the experience is relying on it.
Keep test product IDs and test entitlements out of production configuration.
## Monetization checklist
- [ ] Prompting is client-side, granting is server-side.
- [ ] There is one receipt callback and a product dispatch table.
- [ ] Grants are idempotent and receipt identifiers are recorded.
- [ ] Product configuration is trusted server data.
- [ ] Policy and eligibility checks use current official documentation.
- [ ] Prices, cadence, contents, and disclosures are visible before purchase.
- [ ] Failures leave the receipt retryable instead of silently acknowledging it.
SKILL.md
---
name: roblox-monetization
description: "Use when implementing Roblox GamePasses, Developer Products, subscriptions, private servers, Creator Rewards, or purchase policy checks."
last_reviewed: 2026-08-21
sources:
- https://create.roblox.com/docs/reference/engine/classes/MarketplaceService
- https://create.roblox.com/docs/production/monetization/passes
- https://create.roblox.com/docs/production/monetization/developer-products
- https://create.roblox.com/docs/production/monetization/subscriptions
- https://create.roblox.com/docs/production/monetization/paid-random-items
- https://create.roblox.com/docs/reference/engine/classes/PolicyService
- https://create.roblox.com/docs/creator-rewards
- https://devforum.roblox.com/t/creator-rewards-is-live/3838257
- original
---
# roblox monetization
## When to Load
Load when adding a Game Pass, Developer Product, subscription, private server, Creator Rewards-related product decision, or purchase eligibility check.
## Quick Reference
- Prompt purchases from the client, but grant value only from server-owned code.
- Passes: durable ownership for an experience. Check ownership server-side and refresh after a purchase.
- Developer Products: repeatable consumables. `ProcessReceipt` is the grant path; `PromptProductPurchaseFinished` is not purchase confirmation.
- `BindReceiptHandler` handles Robux-transfer receipts, not Developer Products.
- A receipt that cannot be safely granted must return `NotProcessedYet`. Roblox redelivers it when the player rejoins (there is no time-based retry).
- Use `PolicyService` and current documentation for eligibility-sensitive features. Where policy offers multiple treatments (for example restricted paid random items), present them as a menu with trade-offs. Precedence: user approval authorizes an otherwise permitted action; it does not satisfy a mandatory policy and does not turn a failed or unverified gate into PASS. If the user picks a non-compliant treatment (for example shipping unchanged or odds disclosure alone), do not implement it: present the compliant alternatives and recommend the least disruptive one. Never unilaterally region-lock, hide, or remove a feature the user asked for when a compliant alternative exists.
- Creator Rewards is a platform program, not a grant API. Track eligibility, attribution, engagement, and dashboard reporting separately from purchases and inventory.
- Test failed grants, duplicate receipts, player absence, and interrupted saves before shipping.
- Static presence of `ProcessReceipt` is not receipt correctness; inspect its single owner, durable idempotent grant, and retry paths for unknown products or absent players.
**Need the details?** Load `references/full.md` for purchase flows and failure handling.