Roblox UtilitiesDevlHub Roblox Documentation

Class

MarketplaceService

NotCreatableService
Inherits
Instance › Object
Memory category
Instances

The service responsible for in-experience transactions.

MarketplaceService is responsible for in-experience transactions. The most notable methods are PromptProductPurchase and PromptPurchase, as well as the callback ProcessReceipt which must be defined so that developer product transactions do not fail. BindReceiptHandler is a newer alternative that processes developer product receipts (and Robux transfer receipts) through one or more bound handlers instead of the single ProcessReceipt callback.

MarketplaceService also has methods that fetch information about developer products (GetProductInfoAsync and GetDeveloperProductsAsync), passes (UserOwnsGamePassAsync()), and other assets (PlayerOwnsAssetAsync, PlayerOwnsBundleAsync).

Understanding MarketplaceService is the first step towards learning to monetize an experience on Roblox, as well as learning to use DataStoreService, which is responsible for saving and loading all data related to purchases.

Methods 28#

BindReceiptHandlerRegisters a callback to process receipts of a specific type.
GetDeveloperProductsAsyncReturns a Pages object which contains information for all of the current experience's developer products.Yields
GetProductInfoReturns the product information of an asset using its asset ID.DeprecatedYields
GetProductInfoAsyncReturns the product information of an asset using its asset ID.Yields
GetRobloxSubscriptionDetailsAsyncReturns the subscription details for the given user for the Roblox Subscription ecosystem.Yields
GetSubscriptionProductInfoAsyncReturns the product information of a subscription for the given subscriptionId.Yields
GetUsersPriceLevelsAsyncReturns the regionalized price levels of users, representing the recommended price for an item in each user's regional market.Yields
GetUserSubscriptionDetailsAsyncReturns a table that contains the details of the user's subscription for a given subscriptionId.Yields
GetUserSubscriptionPaymentHistoryAsyncReturns an Array that contains up to one year of the user's subscription payment history for the given subscriptionId.Yields
GetUserSubscriptionStatusAsyncReturns a table that contains the subscription status of the user for the given subscriptionId.Yields
OpenShopOpens a personalized in-game Shop for the given player.
PlayerOwnsAssetReturns whether the given user has the given asset.DeprecatedYields
PlayerOwnsAssetAsyncReturns whether the given user has the given asset.Yields
PlayerOwnsBundleReturns whether the given player owns the given bundle.DeprecatedYields
PlayerOwnsBundleAsyncReturns whether the given player owns the given bundle.Yields
PromptBulkPurchasePrompts a user to purchase multiple avatar items with the given assetId or bundleId.
PromptBundlePurchasePrompts a user to purchase a bundle with the given bundleId.
PromptCancelSubscriptionPrompts a user to cancel a subscription for the given subscriptionId.
PromptGamePassPurchasePrompts a user to purchase a pass with the given gamePassId.
PromptPremiumPurchasePrompts a user to purchase Roblox Premium.Deprecated
PromptProductPurchasePrompts a user to purchase a developer product with the given productId.
PromptPurchasePrompts a user to purchase an item with the given assetId. Does not work for USD Creator Store purchases.
PromptRobloxSubscriptionPurchasePrompts a user to purchase a Roblox Plus subscription.
PromptRobuxTransferAsyncInitiates a Robux transfer from the sender to another user.Yields
PromptSubscriptionPurchasePrompts a user to purchase a subscription for the given subscriptionId.
RankProductsAsyncTakes a list of product IDs and returns a personalized ordered list of those products.Yields
RecommendTopProductsAsync
  • Takes an array of InfoType and returns up to 50 items representing the products a user is most likely to engage with and purchase.
Yields
UserOwnsGamePassAsyncReturns true if the player with the given UserId owns the pass with the given gamePassId.Yields

BindReceiptHandler(transactionType: ReceiptType, handler: Function, filter: Array?): RBXScriptConnection#

BindReceiptHandler registers a callback to process receipts of a specific ReceiptType. You can use it to handle developer product receipts (ReceiptType.DeveloperProduct) and Robux transfer receipts (ReceiptType.RobuxTransferSender and ReceiptType.RobuxTransferReceiver).

For ReceiptType.DeveloperProduct, you can register handlers in two ways:

  • Filtered — Pass a filter array of developer product IDs so the handler only fires for receipts whose ProductId is in that array. Use this to route specific products to dedicated handlers.
  • Catch-all — Omit filter so the handler fires for any developer product receipt not already claimed by a filtered handler.

For developer products, BindReceiptHandler is an alternative to the legacy ProcessReceipt callback. A bound handler takes precedence; if no bound handler matches a developer product receipt, it falls through to ProcessReceipt. This lets you adopt BindReceiptHandler incrementally without removing an existing ProcessReceipt callback.

The handler callback receives a receipt info dictionary and must return an ReceiptDecision value:

  • ReceiptDecision.Processed — Indicates the receipt was successfully processed and all benefits have been granted. The receipt is marked as complete.
  • ReceiptDecision.NotProcessedYet — Indicates the receipt has not been processed yet. The receipt remains unresolved and will be delivered again on the next opportunity.

Receipt Info Dictionary#

The receipt info dictionary passed to the handler contains the following fields:

Key Type Description
PurchaseId string A unique identifier for this specific receipt.
PlayerId number The Class.Player.UserId of the user associated with this receipt.
PlaceIdWherePurchased number The place ID where the transaction was initiated.
ReceiptType Enum.ReceiptType The type of this receipt.
ProductId number The developer product ID. Only present for Enum.ReceiptType.DeveloperProduct receipts.
CurrencyType Enum.CurrencyType The currency used for the purchase. Only present for Enum.ReceiptType.DeveloperProduct receipts.
CurrencySpent number The amount of Robux involved in the transaction. For Enum.ReceiptType.DeveloperProduct receipts, this is the product's price. For Enum.ReceiptType.RobuxTransferSender receipts, this is the amount sent. For Enum.ReceiptType.RobuxTransferReceiver receipts, this is the amount received.
TransferRequestId string The transfer request ID from Class.MarketplaceService:PromptRobuxTransferAsync(). Only present for Enum.ReceiptType.RobuxTransferSender and Enum.ReceiptType.RobuxTransferReceiver receipts.

Receipt Timing#

For Robux transfer receipts, handler is invoked once the transfer settles. A settled receipt is delivered to whichever server the user is currently in (the user does not need to rejoin).

  • ReceiptType.RobuxTransferReceiver — Delivered to the server the receiver is currently in once the transfer settles. If the receiver is offline at that time, delivery happens the next time they join a server.
  • ReceiptType.RobuxTransferSender — Delivered immediately if the transfer settles synchronously. If the transfer is gated on receiver approval (for example, parental consent), delivery happens once the receiver accepts, to whichever server the sender is currently in or on their next join if they are offline.

For developer product receipts, handler is invoked when the purchase completes while the buyer is on a server. If the handler returns ReceiptDecision.NotProcessedYet, or the buyer is not reachable, the receipt remains unresolved and is redelivered on a later opportunity or the next time the buyer joins a server.

The user must be on a server for handler to fire.

Errors#

This method throws an error if:

  • A handler is already registered for the same ReceiptType and product ID combination.
  • A catch-all handler is already registered for the same ReceiptType.
NameTypeDefaultDescription
transactionTypeReceiptTypeThe ReceiptType indicating which kind of receipt to handle.
handlerFunctionA callback function that receives a receipt info dictionary and must return an ReceiptDecision value.
filterArray?An optional array of product IDs. When provided, the handler only fires for receipts matching those product IDs. Not supported for RobuxTransferSender or RobuxTransferReceiver receipt types.
Returns

GetDeveloperProductsAsync(): Instance#

Yields

Returns a Pages object which contains information for all of the current experience's developer products.

Returns
  • Instance — A Pages object whose entries describe the current experience's developer products.

GetProductInfo(assetId: int64, infoType: InfoType = Asset): Dictionary#

YieldsDeprecatedDeprecated

Deprecated. This method has been superseded by GetProductInfoAsync().

Returns the product information of an asset using its asset ID.

NameTypeDefaultDescription
assetIdint64The asset ID of the specified product.
infoTypeInfoTypeAssetAn InfoType enum value specifying the type of information being retrieved.
Returns
  • Dictionary — A dictionary containing information about the queried item, described in the previous tables.

GetProductInfoAsync(assetId: int64, infoType: InfoType = Asset): Dictionary#

Yields

This method provides information about an asset, developer product, or pass based on the asset ID and the InfoType. If an item with the given ID does not exist, this method throws an error.

Information about the queried item is provided in a dictionary with the following keys. Note that not all information is provided or necessarily relevant for the kind of product you're querying.

Key Type Description
Name string The name shown on the asset's page.
Description string The description shown on the asset's page; can be nil if blank.
PriceInRobux number The cost of purchasing the asset using Robux.
UserBasePriceInRobux number The base price of the asset in Robux before any discounts are applied.
PriceDiscountDetails Array An ordered list of discounts representing the difference between UserBasePriceInRobux and PriceInRobux. Each entry contains the following keys:
Type: The type of discount. "RobloxPlusSubscription" indicates that the discount was applied due to the user’s Roblox Plus subscription.
AmountInRobux: number — The value of the discount in Robux.
Percent: number — The percentage of the discount.
ProductId number The product ID if Enum.InfoType is Product.
ProductType string A string describing what the product is. Not to be confused with Enum.MarketplaceProductType.
Created string Timestamp of when the asset was created, for example 2022-01-02T10:30:45Z. Formatted using ISO 8601.
Updated string Timestamp of when the asset was last updated by its creator, for example 2022-02-12T11:22:15Z. Formatted using ISO 8601.
ContentRatingTypeId number Indicates whether the item is marked as 13+ in catalog.
MinimumMembershipLevel number The minimum subscription level necessary to purchase the item.
IsPublicDomain boolean Describes whether the asset can be taken for free.
TargetId number The ID of the product or asset.

Creator Information#

Key Type Description
Creator table Dictionary table of information describing the creator of the asset, containing the following fields:
CreatorType: Either User or Group.
CreatorTargetId: The ID of the creator user or group.
HasVerifiedBadge: Boolean of whether the creator has a verified badge.
Name: The name/username of the creator.
Id: Use CreatorTargetId instead.

Asset Information#

Key Type Description
AssetId number The asset ID if Enum.InfoType is Asset.
AssetTypeId number The type of asset. See Enum.AssetType for the asset type ID numbers.
IconImageAssetId number The asset ID of the product's icon, or 0 if there isn't one.
IsForSale boolean Describes whether the asset is purchasable.
IsLimited boolean Describes whether the asset is a Roblox Limited that is no longer (if ever) sold.
IsLimitedUnique boolean Describes whether the asset is a unique Roblox Limited ("Limited U") item that only has a fixed number sold.
IsNew boolean Describes whether the asset is marked as "new" in the catalog.
Remaining number The remaining number of times a limited unique item may be sold.
Sales number The number of times the asset has been sold.

Collectibles Information#

Key Type Description
CollectibleItemId string The unique item ID of the collectible.
CollectibleProductId string The unique product ID of the collectible.
CollectiblesItemDetails table Dictionary table of information describing the collectible, containing the following fields:
CollectibleLowestAvailableResaleItemInstanceId: The unique item instance ID of the lowest available resale for the collectible.
CollectibleLowestAvailableResaleProductId: The unique product ID of the lowest available resale for the collectible.
CollectibleLowestResalePrice: The lowest resale price for the collectible in Robux.
IsForSale: Boolean of whether the collectible is available for sale (not resale).
IsLimited: Boolean of whether or not the collectible is limited.
TotalQuantity: The total quantity of the collectible available for purchase (not resale).

Sale Location Settings#

Key Type Description
CanBeSoldInThisGame boolean Describes whether the asset is purchasable in the current experience.
SaleLocation table Dictionary table of information describing where the item can be sold, containing the following fields:
SaleLocationType: The type of sale location setting. See Enum.ProductLocationRestriction for the sale location setting ID numbers.
UniverseIds: Array table of universes in which the item can be sold (not currently implemented).

Timed Options#

Key Type Description
TimedOptions array Optional. An array of available timed options with durations and prices. Only present for assets that support timed ownership. Do not hardcode duration values; always retrieve them from this API as they may change. Each entry contains:
Duration: number — The duration in seconds (e.g. 259200 for 3 days, 604800 for 7 days).
Price: number — The price in Robux for this duration.

Batching behavior#

This method is Transparent Batching capable. If you spawn multiple calls concurrently using task.spawn, the engine automatically combines them into fewer HTTP requests behind the scenes. This is faster and helps you avoid rate limits. See Transparent Batching for details and a code example.

NameTypeDefaultDescription
assetIdint64The asset ID of the specified product.
infoTypeInfoTypeAssetAn InfoType enum value specifying the type of information being retrieved.
Returns

GetRobloxSubscriptionDetailsAsync(user: Player): Dictionary#

Yields

This method is a streamlined endpoint to check for a single, platform-wide Roblox subscription product. By providing StartTime (conditionally) and IsOriginExperience to reward long-term loyalists without compromising user data across the platform.

The returned dictionary contains the following fields:

Field Type Description
IsSubscribed bool Returns true if the user has an active Roblox Subscription membership.
IsOriginExperience bool Returns true if the user originally subscribed to Roblox Subscription while inside the current Experience (Universe).
StartTime DateTime? A Datatype.DateTime object representing the time when the user’s subscription period first began. Note: For privacy reasons, this field is only returned if IsOriginExperience is true. If the user subscribed in a different experience or on the web, this field will be nil.
NameTypeDefaultDescription
userPlayerThe user regarding whom to check the subscription status.
Returns

GetSubscriptionProductInfoAsync(subscriptionId: string): Dictionary#

Yields

Returns the product information of a subscription for the given subscriptionId. Because it returns a localized price, you can only call this method from a Script with RunContext.Client.

Key Type Description
Name string The name of the subscription product.
Description string The description of the subscription product.
IconImageAssetId number The asset ID of the subscription product icon.
SubscriptionPeriod Enum.SubscriptionPeriod The duration of the subscription (for example, Month, Year, etc.).
DisplayPrice string Localized price with the appropriate currency symbol for display (for example, $4.99). For users in unsupported countries, DisplayPrice returns a string without specific price information.
DisplaySubscriptionPeriod string Localized subscription period text for display (for example, /month). Can be used together with DisplayPrice.
SubscriptionProviderName string Name of the subscription benefit provider (for example, the name of the associated experience).
IsForSale boolean True if the subscription product is available for sale.
PriceTier number A number that can be used to compare the price of different subscription products. This is not the actual price of the subscription (for example, 499).
PriceInRobux number The equivalent cost of the subscription in Robux. Returns 0 if the subscription product is not available to be purchased in Robux.
NameTypeDefaultDescription
subscriptionIdstringThe ID of the subscription to check.
Returns

GetUsersPriceLevelsAsync(userIds: Array): List<PriceLevelInfo>#

Yields

Returns the regionalized price levels of users, representing the recommended price for an item in each user's regional market. For example, a price level of 100 means that the suggested price for that user (based on their region and purchasing power) is 100 Robux.

See Protect your trades and gifts for more information.

NameTypeDefaultDescription
userIdsArrayAn array of user IDs.
Returns

GetUserSubscriptionDetailsAsync(user: Player, subscriptionId: string): Dictionary#

Yields

Returns a dictionary table containing the details of the user's subscription for the given subscriptionId. The table contains the following keys:

Key Type Description
SubscriptionState Enum.SubscriptionState Current state of this particular subscription.
NextRenewTime Datatype.DateTime Renewal time for this current subscription. May be in the past if the subscription is in Enum.SubscriptionState.SubscribedRenewalPaymentPending|SubscribedRenewalPaymentPending state. This field is will be nil if the subscription will not renew, is Enum.SubscriptionState.Expired|Expired, or the user never subscribed.
ExpireTime Datatype.DateTime When this subscription expires. This field will be nil if the subscription is not cancelled or the user never subscribed.
ExpirationDetails Library.table Table containing the details of the subscription expiration. This field will be nil if the subscription is not in the Enum.SubscriptionState.Expired|Expired state. If populated, the table contains a ExpirationReason key of type Enum.SubscriptionExpirationReason describing why the subscription is expired.

Note that this method can only be called from a Script with RunContext of Server. If you only need to determine the IsSubscribed status of a user, it's recommended to use GetUserSubscriptionStatusAsync as it is faster and more efficient for that particular purpose.

NameTypeDefaultDescription
userPlayerThe Player object whose subscription details you want to check.
subscriptionIdstringThe ID of the subscription to check.
Returns

GetUserSubscriptionPaymentHistoryAsync(user: Player, subscriptionId: string): Array#

Yields

Returns an Array that contains up to one year of the user's subscription payment history for the given subscriptionId, sorted from the most recent status to the least recent. You can only call this method from a Script with RunContext.Server.

Each entry in the payment history Array contains the following keys:

Key Type Description
CycleStartTime Datatype.DateTime Datatype.DateTime at the start of this particular subscription period.
CycleEndTime Datatype.DateTime Datatype.DateTime at the end of this particular subscription period.
PaymentStatus Enum.SubscriptionPaymentStatus Enum.SubscriptionPaymentStatus.Paid if the user paid for this particular subscription period. Enum.SubscriptionPaymentStatus.Refunded if the user refunded this particular subscription period.

Payment History Length#

Only creators affiliated with the subscription product can access up to one year worth of the user's subscription payment history. Non-associated creators can only get the user's current subscription payment status or an empty Array if the user has no active subscription.

Grace Period#

Subscription renewal payments can have some processing time. Payment history doesn't return a table for this period. However, in order to preserve a user's subscription experience during the processing period, GetUserSubscriptionStatusAsync returns IsSubscribed: true for the given user. Don't grant durable items or currency type subscription benefits to the user until after payment has been confirmed for the current cycle.

For example, on August 31, 2023, User A's Subscription B is up for renewal. On September 1, 2023, the payment has yet to be processed. If you call GetUserSubscriptionPaymentHistoryAsync on September 1, 2023 on User A for Subscription B, the first entry of the return value is:

Key Value
CycleStartTime ...
CycleEndTime August 31, 2023
PaymentStatus Enum.SubscriptionPaymentStatus.Paid

Note that since the user is within the grace period, the cycle they have yet to pay for (September 1, 2023) does not appear in the return value at all. This field only populates after the payment has been received and processed.

At the same time, GetUserSubscriptionStatusAsync returns the following result until the renewal payment process fails or the user cancels:

Key Return
IsSubscribed True
IsRenewing True
NameTypeDefaultDescription
userPlayerThe Player whose subscription payment history you want to retrieve.
subscriptionIdstringThe ID of the subscription whose payment history you want to retrieve.
Returns

GetUserSubscriptionStatusAsync(user: Player, subscriptionId: string): Dictionary#

Yields

Returns a table that contains the subscription status of the user for the given subscriptionId. The table contains the following keys:

Key Type Description
IsSubscribed boolean True if the user's subscription is active.
IsRenewing boolean True if the user is set to renew this subscription after the current subscription period ends.

Note that IsSubscribed will be true only when a user has purchased the subscription and the payment has been successfully processed. If the payment for a user's initial subscription purchase is still processing or has failed, IsSubscribed returns false. To understand when a user's subscription status has changed, see the Players.UserSubscriptionStatusChanged event.

NameTypeDefaultDescription
userPlayerThe Player object whose subscription status you want to check.
subscriptionIdstringThe ID of the subscription to check for.
Returns

OpenShop(player: Player): ()#

Opens an in-game Shop as an overlay window for the given Player. Shop displays a personalized list of the experience's passes and developer products ranked for the user.

A default Shop is generated automatically for every game and requires no additional developer setup. You can customize which items appear in the shop from Creator Hub.

This method can be called from either a server Script or a LocalScript. When called from a LocalScript, player must match the local player.

You can call this method in response to any user action, such as a button click, the player reaching a specific location, or joining the experience.

NameTypeDefaultDescription
playerPlayerThe Player for whom to open the shop. If called from a LocalScript, this must be the local player.
Returns

PlayerOwnsAsset(player: Instance, assetId: int64): boolean#

YieldsDeprecatedDeprecated

Deprecated. This method has been superseded by PlayerOwnsAssetAsync().

Returns whether the given user has the given asset.

NameTypeDefaultDescription
playerInstanceThe Player whose inventory is tested for ownership of the given asset.
assetIdint64The asset ID for which the given player's inventory is tested.
Returns

PlayerOwnsAssetAsync(player: Instance, assetId: int64): boolean#

Yields

Returns whether the inventory of a specific user contains an asset, based on the asset ID. This method throws an error if the query fails, so you should wrap calls to this method in pcall().

NameTypeDefaultDescription
playerInstanceThe Player whose inventory is tested for ownership of the given asset.
assetIdint64The asset ID for which the given player's inventory is tested.
Returns

PlayerOwnsBundle(player: Player, bundleId: int64): boolean#

YieldsDeprecatedDeprecated

Deprecated. This method has been superseded by PlayerOwnsBundleAsync().

Returns whether the given player owns the given bundle.

NameTypeDefaultDescription
playerPlayerThe Player whose inventory is tested for ownership of the given bundle.
bundleIdint64The bundle ID for which the given player's inventory is tested.
Returns

PlayerOwnsBundleAsync(player: Player, bundleId: int64): boolean#

Yields

Returns whether the inventory of a specific user contains a bundle, based on the bundle ID. This method throws an error if the query fails, so you should wrap calls to this method in pcall().

NameTypeDefaultDescription
playerPlayerThe Player whose inventory is tested for ownership of the given bundle.
bundleIdint64The bundle ID for which the given player's inventory is tested.
Returns

PromptBulkPurchase(player: Player, lineItems: Array, options: Dictionary): ()#

Prompts a user to purchase multiple avatar items with the given assetId or bundleId. Does not work with non-avatar items.

PromptBulkPurchase only allows prompting from server scripts.

For limited items, original copies are prompted until they run out, regardless of the price. Once original copies are out, resale copies are prompted.

A maximum of 20 items can be added to a single bulk purchase prompt.

PurchaseOptions#

Each line item can optionally include a PurchaseOptions array to control which purchase option appears in the prompt. If omitted, the user is prompted for a permanent purchase only (default behavior).

PurchaseOptions currently supports only one entry. If more than one option is provided, the API throws an error.

Each entry in PurchaseOptions contains:

Key Type Description
Type Enum Enum.PurchaseOption.TimedOption for a timed option, or Enum.PurchaseOption.Permanent for standard purchase.
Value number Required for TimedOption. The duration in seconds.

Do not hardcode duration values. Available durations and prices are determined by the backend and may change at any time. Always retrieve them from one of the following APIs and pass the values through to PurchaseOptions:

NameTypeDefaultDescription
playerPlayerThe user to prompt to purchase items.
lineItemsArray

An array of avatar items to be included in the bulk purchase.

Each line item contains the following structure:

Luau
{
  Type: MarketplaceProductType,
  Id: string,
  PurchaseOptions: { {Type: PurchaseOption, Value: number?} }?
}

Each line item contains the following pairs:

  • Type: The corresponding MarketplaceProductType (Enum).
  • Id: The ID of the asset or bundle.
  • PurchaseOptions: Optional. An array containing a single purchase option to display in the prompt. If omitted, the permanent purchase is prompted. See the PurchaseOptions section below for details.
optionsDictionaryNot available at this time.
Returns

PromptBundlePurchase(player: Instance, bundleId: int64): ()#

Prompts a user to purchase a bundle with the given bundleId.

NameTypeDefaultDescription
playerInstanceThe Player to prompt.
bundleIdint64The ID of the bundle to purchase.
Returns

PromptCancelSubscription(user: Player, subscriptionId: string): ()#

Prompts a user to cancel a subscription for the given subscriptionId. Once the user successfully cancels the subscription, the Players.UserSubscriptionStatusChanged event fires.

NameTypeDefaultDescription
userPlayerThe Player to prompt.
subscriptionIdstringThe ID of the subscription to cancel.
Returns

PromptGamePassPurchase(player: Instance, gamePassId: int64): ()#

Prompts a user to purchase a pass with the given gamePassId.

NameTypeDefaultDescription
playerInstanceThe Player to prompt.
gamePassIdint64The pass ID to purchase. This is the TargetId returned by GetProductInfo() when InfoType is GamePass. It is not the pass's asset ID and not its ProductId.
Returns

PromptPremiumPurchase(player: Instance): ()#

DeprecatedDeprecated

Deprecated. This method has been superseded by PromptRobloxSubscriptionPurchase().

Prompts a user to purchase Roblox Premium. To learn more about Premium and about incorporating Premium incentives into your experience, see Engagement-based payouts.

See Also#

NameTypeDefaultDescription
playerInstanceThe user being prompted to purchase Premium.
Returns

PromptProductPurchase(player: Instance, productId: int64, equipIfPurchased: boolean = true, currencyType: CurrencyType = Default): ()#

Prompts a user to purchase a developer product with the given productId.

NameTypeDefaultDescription
playerInstanceThe Player to prompt.
productIdint64The ID of the developer product to purchase.
equipIfPurchasedbooleantrueIgnored.
currencyTypeCurrencyTypeDefaultIgnored.
Returns

PromptPurchase(player: Instance, assetId: int64, equipIfPurchased: boolean = true, currencyType: CurrencyType = Default): ()#

Prompts a user to purchase an item with the given assetId.

NameTypeDefaultDescription
playerInstanceThe Player to prompt.
assetIdint64The ID of the asset to purchase.
equipIfPurchasedbooleantrueIgnored.
currencyTypeCurrencyTypeDefaultIgnored.
Returns

PromptRobloxSubscriptionPurchase(user: Player): ()#

Prompts a user to purchase a Roblox Plus subscription. When the user successfully subscribes, any experience-defined rewards for the upsell are granted automatically through the engine API.

See Also#

NameTypeDefaultDescription
userPlayerThe Player to be prompted to purchase Roblox Plus.
Returns

PromptRobuxTransferAsync(sender: Player, receiverUserId: int64, amount: int64): string#

Yields

PromptRobuxTransferAsync initiates a Robux transfer from the sender to the user specified by receiverUserId. This is a server-only method and must be called from a Script with RunContext set to Server.

After a successful transfer, both the sender and receiver will have receipts delivered to their respective BindReceiptHandler callbacks:

Both receipts include a TransferRequestId field matching the transferRequestId returned by this method, which you can use for logging or to correlate sender and receiver receipts.

Receipt Timing#

Both receipts are delivered to whichever server the corresponding user is currently in once the transfer settles (neither side needs to rejoin). If a transfer is gated on receiver approval, for example parental consent for the receiver's account, it does not settle until approval lands; receipts are delivered after that point.

Errors#

This method throws an error if:

NameTypeDefaultDescription
senderPlayerThe Player initiating the transfer. Must be a valid player currently in the server.
receiverUserIdint64The UserId of the user who will receive the Robux.
amountint64The amount of Robux to transfer. Must be a positive integer.
Returns

PromptSubscriptionPurchase(user: Player, subscriptionId: string): ()#

Prompts a user to purchase a subscription for the given subscriptionId.

NameTypeDefaultDescription
userPlayerThe Player object to be prompted to subscribe.
subscriptionIdstringThe ID of the subscription to subscribe to.
Returns

RankProductsAsync(productIdentifiers: Array): List<RankedItem>#

Yields

Takes a list of product IDs and returns a personalized ordered list of those products.

This API has a client-side throttling limit of 10 requests per minute. If you exceed this limit, wait 60 seconds and make the request again.

NameTypeDefaultDescription
productIdentifiersArray

An array of objects identifying the products you want to rank. This array can include up to 50 items.

Each ProductIdentifier has:

Luau
local ProductIdentifier = {
	InfoType = Enum.InfoType.GamePass,
	Id = 123456
}
Returns

RecommendTopProductsAsync(infoTypes: Array): List<RankedItem>#

Yields

Takes an array of InfoType and returns up to 50 items representing the products a user is most likely to engage with and purchase. If no recommendations can be determined, the method returns an empty list.

This API has a client-side throttling limit of 5 requests per minute. If you exceed this limit, wait 60 seconds and make the request again.

NameTypeDefaultDescription
infoTypesArray

An array of InfoType values specifying the types of product to retrieve recommendations for.

Supported InfoTypes: InfoType.GamePass, InfoType.Product.

Luau
local infoTypes = {
	Enum.InfoType.GamePass,
	Enum.InfoType.Product
}
Returns

UserOwnsGamePassAsync(userId: User, gamePassId: int64): boolean#

Yields

Returns true if the user with the given UserId owns the pass with the given gamePassId (not to be confused with an asset ID). You can use this method on both the client and the server.

Caching Behavior#

The results of this function are cached so that repeated calls are returned faster. When the PromptGamePassPurchaseFinished event fires, the cache gets updated to reflect the latest ownership state of the associated game pass.

If the user purchases a game pass outside of the experience while remaining in the same session, the cache is eventually updated, but this process might take several minutes to propagate.

When a user first enters a server after purchasing a game pass, this functions always returns true.

Batching behavior#

This method is Transparent Batching capable. If you spawn multiple calls concurrently using task.spawn, the engine automatically combines them into fewer HTTP requests behind the scenes. This is faster and helps you avoid rate limits. See Transparent Batching for details.

NameTypeDefaultDescription
userIdUserThe UserId of the Player whose inventory you're checking.
gamePassIdint64The pass ID you want to check for. Not to be confused with an asset ID.
Returns

Events 8#

PromptBulkPurchaseFinishedFires when a purchase prompt for bulk avatar items is closed.
PromptBundlePurchaseFinishedFires when a bundle purchase prompt closes.
PromptGamePassPurchaseFinishedFires when a purchase prompt for a pass is closed.
PromptPremiumPurchaseFinishedFires when a purchase prompt for Roblox Premium is closed.
PromptProductPurchaseFinishedFires when a purchase prompt for a developer product is closed. Do not use this event to process purchases.
PromptPurchaseFinishedFires when a purchase prompt for an affiliate gear sale or other asset is closed. Does not fire for developer product or pass prompts.
PromptRobloxSubscriptionPurchaseFinishedFires when a purchase prompt for Roblox Plus is closed.
PromptSubscriptionPurchaseFinishedFires when a purchase prompt for a subscription is closed.

PromptBulkPurchaseFinished(player: Instance, status: MarketplaceBulkPurchasePromptStatus, results: Dictionary)#

This event fires when a purchase prompt for a bulk avatar items closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

Note: This is not a trusted event from the client. To check if the user owns the items purchased, use MarketplaceService.PlayerOwnsAssetAsync or MarketplaceService.PlayerOwnsBundleAsync.

NameTypeDefaultDescription
playerInstanceThe Player who received the prompt.
statusMarketplaceBulkPurchasePromptStatusThe status of the bulk purchase.
resultsDictionary

The table type containing the line items and their status in the following format:

Luau
{
  RobuxSpent: number
  Items: {
    {
      type: MarketplaceProductType,
      id: string,
      status: MarketplaceItemPurchaseStatus
    },
    ...
  }
}

Each line item contains the following pairs:

PromptBundlePurchaseFinished(player: Instance, bundleId: int64, wasPurchased: boolean)#

This event fires when a purchase prompt for a bundle closes. Use PlayerOwnsBundleAsync() to verify ownership instead of trusting this client-originated event.

NameTypeDefaultDescription
playerInstanceThe Player who received the prompt.
bundleIdint64The ID of the bundle shown in the prompt.
wasPurchasedbooleanWhether the bundle was purchased.

PromptGamePassPurchaseFinished(player: Instance, gamePassId: int64, wasPurchased: boolean)#

This event fires when a purchase prompt for a pass closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

See Also#

NameTypeDefaultDescription
playerInstanceThe Player who received the prompt.
gamePassIdint64The ID number of the pass shown in the prompt. Not to be confused with an asset ID.
wasPurchasedbooleanIndicates if the user pressed OK (true), Cancel (false) on the purchase prompt, or if the purchase prompt errored (false).

When PromptGamePassPurchaseFinished fires, it updates the cache used by UserOwnsGamePassAsync() to reflect the current ownership state.

PromptGamePassPurchaseFinished should only be listened to in a server script. When used on the server, values such as wasPurchased reflect the final outcome of the purchase attempt. When used in a local script, these values should not be relied on for validation or game logic.

PromptPremiumPurchaseFinished()#

This event fires when a purchase prompt for Roblox Premium closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

See Also#

PromptProductPurchaseFinished(userId: int64, productId: int64, isPurchased: boolean)#

IMPORTANT: Do not use the PromptProductPurchaseFinished event to process purchases; instead, use the ProcessReceipt callback. The firing of PromptProductPurchaseFinished does not mean that a user has successfully purchased an item.

This event fires when a purchase prompt for a developer product closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK. The firing of this event does not mean that a user has successfully purchased an item.

While you can use the PromptProductPurchaseFinished event to detect when a user closes a purchase prompt, you should not use it to process purchases because those purchases might still fail in the backend for several reasons. For example, if a Roblox system is offline, or if the product price has changed and the user now doesn't have enough Robux to make the purchase. To process purchases, you must use ProcessReceipt. Using ProcessReceipt allows you to confirm that the purchase has succeeded before you grant the user the item they have purchased.

The PromptProductPurchaseFinished event fires with a Player.UserId instead of a reference to the Player object.

See Also#

NameTypeDefaultDescription
userIdint64The UserId of the user who received the developer product prompt.
productIdint64The ID number of the developer product shown in the prompt. Not to be confused with an asset ID.
isPurchasedbooleanIndicates if the user pressed OK (true), Cancel (false) on the purchase prompt, or if the purchase prompt errored (false).

Do not use this parameter to process developer product purchases.

PromptPurchaseFinished(player: Instance, assetId: int64, isPurchased: boolean)#

This event fires when a purchase prompt for an affiliate gear sale or other asset closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

This event does not fire for developer product or pass prompts.

See Also#

NameTypeDefaultDescription
playerInstanceThe Player who received the prompt.
assetIdint64The asset ID of the item shown in the prompt.
isPurchasedbooleanIndicates if the user pressed OK (true), Cancel (false) on the purchase prompt, or if the purchase prompt errored (false).

This might not accurately reflect if the purchase itself has been successfully processed.

PromptRobloxSubscriptionPurchaseFinished(user: Player, didTryPurchasing: boolean)#

This event fires when a purchase prompt for Roblox Plus closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

Note that this event firing does not guarantee the subscription was successfully processed. Listen to Player.HasRobloxSubscription via Instance:GetPropertyChangedSignal() on the server to confirm a subscription change before granting rewards.

See Also#

NameTypeDefaultDescription
userPlayerThe Player who received the prompt.
didTryPurchasingbooleanWhether the user attempted to purchase Roblox Plus.

PromptSubscriptionPurchaseFinished(user: Player, subscriptionId: string, didTryPurchasing: boolean)#

This event fires when a purchase prompt for an affiliate gear sale or other asset closes. For example, when a user receives the purchase prompt and clicks Cancel, or when they receive a success or error message and click OK.

See Also#

NameTypeDefaultDescription
userPlayerThe Player who received the prompt.
subscriptionIdstringThe ID of the subscription with a status change.
didTryPurchasingbooleanWhether the user attempted to purchase the subscription.

Callbacks 1#

ProcessReceiptA callback to process receipts of developer product purchases.

ProcessReceipt(receiptInfo: Dictionary): ProductPurchaseDecision#

ProcessReceipt is a callback to process receipts from developer product purchases. You can sell developer products inside an experience using MarketplaceService functions, or outside an experience on the Store tab of your experience details page.

You should only set the ProcessReceipt callback one time in a single server-side Script. This callback must handle the receipts for all developer products you have for sale.

IMPORTANT: It's highly recommended that you properly implement the ProcessReceipt callback in order to sell your developer products. You should use ProcessReceipt to grant users their purchased product over any other granting method. If your ProcessReceipt implementation isn't correct, you will not be able to grant users the products they have purchased on the Store tab of your experience details page.

Guarantees#

The ProcessReceipt callback is called for all unresolved developer product purchases when:

  • A user successfully completes the purchase of a developer product.
  • A successful developer product purchase prompt appears to the user.
  • A user joins the server.

A purchase is considered successfully initiated when:

  • The purchase is processed on Roblox's backend.
  • The funds are placed in escrow.

A purchase is considered resolved when:

Unresolved Developer Product Purchases#

An unresolved developer product purchase takes place when a user's purchase of a developer product has not yet been acknowledged by the server through the ProcessReceipt function.

Unresolved developer product purchases are not removed or refunded after the escrow period expires.

Retries and Timeouts#

ProcessReceipt has no time-based retry mechanism. If a user makes a purchase that returns a ProductPurchaseDecision enum of NotProcessedYet, the ProcessReceipt callback is only called again on the same server if:

  • The user successfully initiates another developer product purchase.
  • The user re-joins any server under the same experience.

ProcessReceipt also has no timeout for yielded callbacks. A ProcessReceipt callback can yield for as long as the server is running, and the callback result is still accepted when the result returns.

Limitations#

  • If you don't implement a ProcessReceipt callback, your receipts will be auto-acknowledged. You can't get a receipt back after it has been acknowledged.
  • When there are multiple purchases pending for a user, ProcessReceipt callbacks are called in a non-deterministic order.
  • The user must be on the server for the ProcessReceipt callback to be invoked.
  • The user does not have to be on the server for the result of the ProcessReceipt callback to be recorded on the backend.
  • The ProcessReceipt callback for a specific purchase might run on two different servers at the same time if the user joins the second server before the callback returns on the first server.
  • The ProcessReceipt callback might still fail to be recorded on the backend, even if it returns a ProductPurchaseDecision enum of PurchaseGranted. When this happens, the purchase remains unresolved.
NameTypeDefaultDescription
receiptInfoDictionary

The receiptInfo table passed to this callback contains the following data:

  • PurchaseId — A unique identifier for the specific purchase.
  • PlayerId — The user ID of the user who made the purchase.
  • ProductId — The ID of the purchased product.
  • PlaceIdWherePurchased — The place ID in which the purchase was made. Depending on where the user is during gameplay, the purchase place's ID can be the same as or different from the current place's ID.
  • CurrencySpent — The amount of currency spent in the transaction.
  • CurrencyType — The type of currency spent in the purchase; always CurrencyType.Robux.
  • ProductPurchaseChannel — How the user acquired the developer product. One of ProductPurchaseChannel.
Returns
  • ProductPurchaseDecision —

    An enum that represents how the developer product receipt was processed.

    • PurchaseGranted:
      • Indicates that the experience successfully granted the player the developer product.
      • Indicates to Roblox that the developer product sale was successful.
    • NotProcessedYet:
      • Indicates that the experience failed to grant the player the developer product.

Inherited members#

Inherited from Instance 58
Properties (10)

Archivable, archivable, Capabilities, IsInSandbox, Name, Parent, PredictionMode, RobloxLocked, Sandboxed, UniqueId

Methods (39)

AddTag, children, ClearAllChildren, Clone, clone, Destroy, destroy, FindFirstAncestor, FindFirstAncestorOfClass, FindFirstAncestorWhichIsA, FindFirstChild, findFirstChild, FindFirstChildOfClass, FindFirstChildWhichIsA, FindFirstDescendant, GetActor, GetAttribute, GetAttributeChangedSignal, GetAttributes, GetChildren, getChildren, GetDebugId, GetDescendants, GetFullName, GetStyled, GetStyledPropertyChangedSignal, GetTags, HasTag, IsAncestorOf, IsDescendantOf, isDescendantOf, IsPropertyModified, QueryDescendants, Remove, remove, RemoveTag, ResetPropertyToDefault, SetAttribute, WaitForChild

Events (9)

AncestryChanged, AttributeChanged, ChildAdded, childAdded, ChildRemoved, DescendantAdded, DescendantRemoving, Destroying, StyledPropertiesChanged

Inherited from Object 6
Properties (2)

ClassName, className

Methods (3)

GetPropertyChangedSignal, IsA, isA

Events (1)

Changed