MarketplaceService

MarketplaceService : Instance

Overview

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

Creators must define the ProcessReceipt callback function to ensure that deliveries are not missed when a product is sold, and are responsible for using DataStore or similar mechanisms to make sure deliveries complete successfully.

Properties

ProcessReceipt

Value

A callback function that processes undelivered receipts from successfully purchased products.

Code Samples

Methods

GetProductInfo

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

Parameters

number ProductId	The ID of the product.
Enum.InfoType InfoType	The type of the product.

Return

Value	A dictionary containing the product information. string Name: Product name string Description: Product description number ProductId: Product ID string ProductType: Product type number PriceInBLUC: Product price number Created: Time the product was created (UNIX timestamp) number Updated: Time the product was last updated (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 about all world products.

Parameters

Return

Pages	An object containing information about every world product 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

Requests the purchase of the product corresponding to the world product ID (productId). (A purchase window is displayed through the system UI.)

Parameters

Player Player	The Player who will purchase the product.
number ProductId	The 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 by a purchase request (PromptProductPurchase) is closed. If the purchase succeeds, true is passed to isPurchased; if the user cancels or the purchase fails, false is passed.

This event should only be used to detect whether the purchase window has been closed. It must never be used to process delivery for purchased products.

Parameters

string UserId	The UserId of the Player who requested the purchase.
number ProductId	The ID of the requested product.
bool bIsPurchased	Whether the purchase succeeded.

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

An event is triggered that returns information about undelivered receipts among 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	A dictionary containing the receipt information for a successfully purchased product. string PurchaseId: Receipt ID string PlayerId: The Player's UserId number ProductId: Product ID number CurrencySpent: Amount of currency spent on the transaction number PurchaseDateTime: Time the product was purchased (UNIX timestamp)

Return

Enum.ProductPurchaseDecision	The delivery status of the world product. PurchaseGranted: The product has been successfully delivered to the Player. NotProcessedYet: The product has not yet been 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

World Product Sales