MarketplaceService

MarketplaceService : Instance

Overview

MarketplaceService is a service responsible for handling in-world purchases and processing delivery upon successful transactions.

Creators must define the ProcessReceipt callback function to ensure deliveries are not omitted, and are responsible for using DataStore or similar to complete deliveries successfully.

Properties

Methods

GetProductInfo

Returns the product information corresponding to the product ID (productId) and product type (Enum.InfoType).

Parameters

number ProductId	Product Id
Enum.InfoType InfoType	Product Type

Return

Value	A dictionary containing product information string Name: Product name string Description: Product description number ProductId: Product Id string ProductType: Product type number PriceInBLUC: Product price number Created: Product creation time (UNIX timestamp) number Updated: Product modification time (UNIX timestamp)

Code Samples

local MarketplaceService = game:GetService("MarketplaceService")

local function Request_GetProductInfo(productId)
    local success, errorOrProductInfo = pcall(function()
        return MarketplaceService:GetProductInfo(productId, Enum.InfoType.Product)
    end)
    
    if not success then
        print("Error: " .. errorOrProductInfo .. " / ProductId : " .. productId)
        
    else
        local productInfo = errorOrProductInfo 
        print("World Product Name: " .. tostring(productInfo.Name))
        print("ProductId: " .. tostring(productInfo.ProductId))
        print("ProductType: " .. tostring(productInfo.ProductType))
        print("PriceInBLUC: " .. tostring(productInfo.PriceInBLUC))
        print("Description: " .. tostring(productInfo.Description))
        print("Created: " .. productInfo.Created)
        print("Updated: " .. productInfo.Updated)
    end
end

GetWorldProductsAsync

Returns a Pages Object containing information on all world products.

Parameters

Return

Pages	An Object containing information about all world products in the current world

Code Samples

local MarketplaceService = game:GetService("MarketplaceService")

local function Request_GetWorldProductsAsync()
    local success, errorOrWorldProducts = pcall(function()
        return MarketplaceService:GetWorldProductsAsync()
    end) 
    
    if not success then
        print("Error: " .. errorOrWorldProducts)
        
    else
        local worldProducts = errorOrWorldProducts
        
        local pageCount = 1	  
        local dataList = {}
			
        while true do
            local currentPage = worldProducts:GetCurrentPage()	
		    
            -- Exit loop if it's the last page 
            if worldProducts.IsFinished or currentPage == nil then           	
                print(pageCount .. " page IsFinished : " .. tostring(worldProducts.IsFinished))
                break
            else
                worldProducts:AdvanceToNextPageAsync()
                pageCount = pageCount + 1
            end
	    
            -- Each page contains up to 100 product entries
            for _, productInfo in pairs(currentPage) do		
                local i = #dataList + 1
				
                print("------ " .. i .. " ------")
                print("World Product Name: " .. tostring(productInfo.Name))
                print("ProductId: " .. tostring(productInfo.ProductId))
                
                print("ProductType: " .. tostring(productInfo.ProductType))
                print("PriceInBLUC: " .. tostring(productInfo.PriceInBLUC))
                print("Description: " .. tostring(productInfo.Description))
                print("Created: " .. productInfo.Created)
                print("Updated: " .. productInfo.Updated)
	
                table.insert(dataList, productInfo)
            end
        end
    end
end

PromptProductPurchase

Request the purchase of the product corresponding to the product ID (productID). (Purchase window appears using the system UI.)

Parameters

Player Player	The player purchasing the product
number ProductId	World product Id

Return

void

Code Samples

local MarketplaceService = game:GetService("MarketplaceService")

local function Request_PromptProductPurchase(player, productId)
    local success, error = pcall(function()
        MarketplaceService:PromptProductPurchase(player, productId)
    end)
	
    if not success then
        print("Error: " .. error .. " / ProductId : " .. productId)        
    end	
end

Events

PromptProductPurchaseFinished

This event is triggered when the purchase window, opened via request Purchase (PromptProductPurchase), is closed. If the purchase is successful, "true" will be sent to isPurchased; if the user cancels or the purchase fails, "false" will be sent to isPurchased.

This event should only be used to detect whether the purchase window is closed. It must never be used to process the deliver of purchased products.

Parameters

string UserId	The UserId of the player requesting the purchase
number ProductId	Product Id of the purchase request
bool bIsPurchased	Purchase success status

Code Samples

local Players = game:GetService("Players")
local MarketplaceService = game:GetService("MarketplaceService")

local function OnPromptPurchaseFinished(userId, productId, isPurchased)
    local player = Players:GetPlayerByUserId(userId)
    
    print(player.Name .. " / ProductID : " .. productId .. " / isPurchased : " .. tostring(isPurchased))
end
MarketplaceService.PromptProductPurchaseFinished:Connect(OnPromptPurchaseFinished)

Callback

ProcessReceipt

Trigger the event that returns undelivered receipt information from successfully purchased products.

Trigger Conditions

• When a world product is successfully purchased (the successful purchase popup is shown to the user),

  • if there are any undelivered products, those previous pending items will also be triggered together when the new purchase is made.

• When the user connects (or reconnects) to the server

How to Update Delivery Status

• After successfully delivering the product, return Enum.ProductPurchaseDecision.PurchaseGranted.

Important Notes

• The ProcessReceipt event should be connected only once in a server-side script.

• This callback can yield indefinitely and remains valid until it receives a response, as long as the server is running.

• If there are multiple undelivered receipts, each one will be triggered individually, and the order of these callbacks is non-deterministic.

• The callback will only be triggered when the user is present on the server.

  • However, the result of the callback may still be recorded on the backend even if the user is no longer on the server.

• Returning PurchaseGranted from the callback does not guarantee that the backend will successfully record it. In such cases, the receipt status remains unchanged (remains undelivered).

• Products in an undelivered state will have their funds held in an Escrow state.

Parameters

table Receipt	The dictionary containing receipt information of purchased products string PurchaseId: Receipt Id string PlayerId: Player's UserId number ProductId: Product Id number CurrencySpent: Amount of currency used number PurchaseDateTime: Time of purchase (UNIX timestamp)

Return

Enum.ProductPurchaseDecision	World product delivery status PurchaseGranted: Product successfully delivered to the player NotProcessedYet: Product not yet delivered

Code Samples

local Players = game:GetService("Players")
local MarketplaceService = game:GetService("MarketplaceService")

local ProductDeliverer = {}

-----------------------------------------------------------------------------
-- You can define a function for each product ID in a table as shown below to 
-- implement custom delivery logic for each product.
ProductDeliverer[Enter the product number here.] = function(player)
    local success, resultOrError = pcall(function()
        -- Deliver the product to the player and handle saving using DataStore
        
        -- Tip.
        -- When saving product information using DataStore
        -- it's recommended to use IncrementAsync or UpdateAsync
        -- to prevent network conflicts or race conditions.
                
        -- Return "true" when the product has been successfully delivered and saved
        return true
    end)
    
    if success and resultOrError then
        return true
        
    else
        return false, resultOrError
    end
end

-----------------------------------------------------------------------------
-- Callback for handling the receipt triggered after a successful product purchase
local function OnProcessReceipt(receiptInfo)	
    -- Receipt information
    local success, error = pcall(function()	
        print("PurchaseId: " .. receiptInfo.PurchaseId)
        print("UserId: " .. receiptInfo.PlayerId)
        print("ProductId: " .. receiptInfo.ProductId)
        print("CurrencySpent: " .. receiptInfo.CurrencySpent)
        print("PurchaseDateTime: " .. receiptInfo.PurchaseDateTime)
    end)
    
    if not success then
        print("Error: " .. tostring(error))
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end
    
    -- If the player is valid 
    local productId = receiptInfo.ProductId        
    local userId = receiptInfo.PlayerId
    
    local player = Players:GetPlayerByUserId(userId)  
    if player == nil then
        print("Error: player is nil")
        return Enum.ProductPurchaseDecision.NotProcessedYet	
    end  
    
    -- Trigger the product delivery function
    local delivererFunc = ProductDeliverer[productId]
    local success, error = delivererFunc(player)
    
    -- If the product is successfully delivered
    if success then
        -- Return the status as delivered
        print("Item delivery successful / ProductId : " .. productId)
        return Enum.ProductPurchaseDecision.PurchaseGranted
        
    -- If product delivery fails
    else
        print("Error: " .. tostring(error))
        return Enum.ProductPurchaseDecision.NotProcessedYet
    end
end
MarketplaceService.ProcessReceipt = OnProcessReceipt

See also

Marketplace