Merch Booth

The MerchBooth developer module lets you offer avatar assets, passes, and developer products for sale directly within your game. Players can browse items, preview assets on their own avatar, purchase items, and instantly use or equip them — all without leaving your game. This can help you monetize your game and gain revenue through the 40% affiliate fee associated with selling other creators' items.

Module usage#

Installation#

To use the MerchBooth module in a game:

1. From Studio's Window menu or Home tab toolbar, open the Toolbox and select the Creator Store tab.

   

2. Make sure the Models sorting is selected, then click the See All button for Categories.

   

3. Locate and click the Packages tile.

4. Locate the Merch Booth module and click it, or drag-and-drop it into the 3D view.

   

5. In the Explorer window, move the entire MerchBooth model into ReplicatedStorage. Upon running the game the module will begin running.

Configuration#

The module is preconfigured to work for most use cases, but it can be easily customized through the configure function. For example, to create a lighter theme and disable the default Filter button in the upper-left area of the catalog view:

1. In StarterPlayerScripts, create a new LocalScript and rename it to ConfigureMerchBooth.

   

2. Paste the following code into the new script.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   MerchBooth.configure({
       backgroundColor = Color3.fromRGB(220, 210, 200),
       textSize = 17,
       textFont = Enum.Font.Fondamento,
       textColor = Color3.fromRGB(20, 20, 20),
       useFilters = false
   })

   

Add items#

What's a merch booth without merch? The following sections outline how to add avatar assets, passes, and developer products to your merch booth.

Avatar assets#

Items such as clothing and accessories must be added through their asset ID located on the item's detail page in the Avatar Shop.

1. Create a Script within ServerScriptService and paste in the following code.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
   
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId)
       end)
       if not success then
           warn(errorMessage)
       end
   end

2. Copy item asset IDs from their Avatar Shop website URL. For example, the ID of Roblox Baseball Cap is 607702162.

   

3. Paste each copied ID into a comma-delimited list within the items table. By default, items appear in the catalog view in alphabetical order, but you can customize sorting using setCatalogSort.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
       607702162, -- Roblox Baseball Cap
       4819740796, -- Robox
       1374269, -- Kitty Ears
       11884330, -- Nerd Glasses
       10476359, -- Paper Hat
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId)
       end)
       if not success then
           warn(errorMessage)
       end
   end

Passes#

Adding passes requires pass IDs which can be located in the Creator Dashboard.

1. Create a Script within ServerScriptService and paste in the following code.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
   
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId)
       end)
       if not success then
           warn(errorMessage)
       end
   end

2. Navigate to the Creator Dashboard and select the game.

3. In the left column, under Monetization, select Passes.

4. Hover over a pass' thumbnail, click the ⋯ button, and select Copy Asset ID from the context menu.

   

5. Paste each copied ID into a comma-delimited list within the items table and include InfoType.GamePass as the second parameter for addItemAsync to indicate that the items are passes. By default, items will appear in the catalog view in alphabetical order, but sorting can be customized via setCatalogSort.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
       4343758, -- ColdFyre Armor
       28521575, -- Slime Shield
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId, Enum.InfoType.GamePass)
       end)
       if not success then
           warn(errorMessage)
       end
   end

Developer Products#

Adding developer products requires product IDs which can be located in the Creator Dashboard.

1. Create a Script within ServerScriptService and paste in the following code.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
   
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId)
       end)
       if not success then
           warn(errorMessage)
       end
   end

2. Navigate to the Creator Dashboard and select the game.

3. In the left column, under Monetization, select Developer Products.

4. Hover over a product's thumbnail, click the ⋯ button, and select Copy Asset ID from the context menu.

   

5. Paste each copied ID into a comma-delimited list within the items table and include InfoType.Product as the second parameter for addItemAsync to indicate that the items are developer products. By default, items appear in the catalog view in alphabetical order, but you can customize sorting using setCatalogSort.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   local items = {
       1236602053, -- Mana Refill
       1257880672, -- Healing Potion
   }
   
   for _, assetId in items do
       local success, errorMessage = pcall(function()
           MerchBooth.addItemAsync(assetId, Enum.InfoType.Product)
       end)
       if not success then
           warn(errorMessage)
       end
   end

Custom catalog button#

By default, a right-side catalog button lets players open the booth at any time.

In some cases, it may be useful to remove this button and connect your own:

1. Create a new button as outlined in Buttons.

2. Create a LocalScript as a child of the button object.

   

3. Paste the following code into the new script.

   LuauCopy

   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   -- Remove the default catalog button
   MerchBooth.toggleCatalogButton(false)
   
   -- Connect the custom button
   script.Parent.Activated:Connect(function()
       MerchBooth.openMerchBooth()
   end)

Shoppable regions#

A helpful way to drive purchases in your game is to automatically show the merch booth when a player enters an area.

To create a shoppable region:

1. Create an Anchored block that encompasses the detection region. Make sure the block is tall enough to collide with the PrimaryPart of character models (HumanoidRootPart by default).

   

2. Using the Tags section of the block's properties, apply the tag ShopRegion to the block so that CollectionService detects it.

3. Set the part's Transparency to the maximum to hide it from players in the game. Also disable its CanCollide and CanQuery properties so that objects do not physically collide with it and raycasts do not detect it.

1. Insert a new LocalScript under StarterPlayerScripts.

   

2. In the new script, paste the following code which uses the Touched and TouchEnded events to detect when characters enter/leave the region and calls openMerchBooth and closeMerchBooth to open/close the booth GUI.

   LuauCopy

   local Players = game:GetService("Players")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local CollectionService = game:GetService("CollectionService")
   
   local MerchBooth = require(ReplicatedStorage.MerchBooth)
   
   -- Remove the default catalog button
   MerchBooth.toggleCatalogButton(false)
   
   local function setupRegion(region: BasePart)
       region.Touched:Connect(function(otherPart)
           local character = Players.LocalPlayer.Character
           if character and otherPart == character.PrimaryPart then
               MerchBooth.openMerchBooth()
           end
       end)
   
       region.TouchEnded:Connect(function(otherPart)
           local character = Players.LocalPlayer.Character
           if character and otherPart == character.PrimaryPart then
               MerchBooth.closeMerchBooth()
           end
       end)
   end
   
   -- Iterate through existing tagged shop regions
   for _, region in CollectionService:GetTagged("ShopRegion") do
       setupRegion(region)
   end
   -- Detect when non-streamed shop regions stream in
   CollectionService:GetInstanceAddedSignal("ShopRegion"):Connect(setupRegion)

Proximity prompts#

As an alternative to the 2D catalog view, you can add proximity prompts over in-game objects. This encourages players to discover items in the 3D environment, preview them on their own avatar, purchase them, and instantly equip them. See addProximityButton for details.

Change the equip effect#

By default, the merch booth shows a generic sparkle effect when a player equips an item from it. To change the effect, set particleEmitterTemplate to your own instance of a ParticleEmitter in a configure call.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local myParticleEmitter = Instance.new("ParticleEmitter")
myParticleEmitter.SpreadAngle = Vector2.new(22, 22)
myParticleEmitter.Lifetime = NumberRange.new(0.5, 1.5)
myParticleEmitter.Shape = Enum.ParticleEmitterShape.Sphere
myParticleEmitter.Transparency = NumberSequence.new(0, 1)
myParticleEmitter.RotSpeed = NumberRange.new(200, 200)

MerchBooth.configure({
	particleEmitterTemplate = myParticleEmitter
})

GUI visibility#

By default, the merch booth hides all ScreenGuis and CoreGuis when its UI appears, including the chat, leaderboard, and others included by Roblox. If you want to disable this behavior, set hideOtherUis to false in a configure call.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.configure({
	hideOtherUis = false
})

Character movement#

It can be advantageous to prevent a character from moving while they are in the merch booth. This can be done by setting disableCharacterMovement to true in a configure call.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.configure({
	disableCharacterMovement = true
})

API reference#

Types#

Item#

Items in the merch booth are represented by a dictionary with the following key-value pairs. Items can be gathered through the getItems function or the itemAdded event.

Enums#

MerchBooth.Controls#

Used along with setControlKeyCodes to customize the keys and gamepad buttons for interacting with the merch booth.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.setControlKeyCodes(MerchBooth.Controls.ProximityPrompts, {
	keyboard = Enum.KeyCode.Q,
	gamepad = Enum.KeyCode.ButtonL1
})

Functions#

configure#

Overrides default client-side configuration options through the following keys/values in the config table. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.configure({
	backgroundColor = Color3.fromRGB(255, 255, 255),
	textSize = 16,
	textFont = Enum.Font.Roboto,
	textColor = Color3.fromRGB(20, 20, 20),
	hideOtherUis = false,
})

addItemAsync#

Asynchronously adds an item to the merch booth so that it's eligible for purchase in the game. assetId is the item's asset ID, productType is the item's InfoType enum, and hideFromCatalog can be used to hide the item in the catalog view.

See Adding Items for details, as usage varies slightly for assets versus game passes or developer products.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local items = {
	607702162, -- Roblox Baseball Cap
	4819740796, -- Robox
	1374269, -- Kitty Ears
	11884330, -- Nerd Glasses
	10476359, -- Paper Hat
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId)
	end)
	if not success then
		warn(errorMessage)
	end
end

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local items = {
	4343758, -- ColdFyre Armor
	28521575, -- Slime Shield
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId, Enum.InfoType.GamePass)
	end)
	if not success then
		warn(errorMessage)
	end
end

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local items = {
	1236602053, -- Mana Refill
	1257880672, -- Healing Potion
}

for _, assetId in items do
	local success, errorMessage = pcall(function()
		MerchBooth.addItemAsync(assetId, Enum.InfoType.Product)
	end)
	if not success then
		warn(errorMessage)
	end
end

getItems#

Returns a dictionary representing all of the currently registered items. Each key is an item's asset ID as a string, and each key's value is an Item. This function can only be called from a Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local items = MerchBooth.getItems()
	print(items)
end

removeItem#

Unregisters an item previously added with addItemAsync, removing its tile in the catalog view and any proximity prompts assigned to it. This function can only be called from a Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	-- After some time, remove the item
	task.wait(5)
	MerchBooth.removeItem(4819740796)
end

addProximityButton#

Adds a proximity prompt over the given adornee that will trigger the display of an item's purchase view, given its asset ID. This can be used as an alternative to the 2D catalog view, encouraging players to discover items in the 3D environment.

Note that an item must be added via addItemAsync before a proximity button can be assigned to it. See also removeProximityButton to remove the proximity prompt from an object.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local item = Workspace:FindFirstChild("Robox")
	if item then
		MerchBooth.addProximityButton(item, 4819740796)
	end
end

removeProximityButton#

Removes a proximity prompt generated through addProximityButton. This function can only be called from a Script.

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Workspace = game:GetService("Workspace")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	local item = Workspace:FindFirstChild("Robox")
	if item then
		MerchBooth.addProximityButton(item, 4819740796)
	end

	-- After some time, remove the prompt
	task.wait(5)
	MerchBooth.removeProximityButton(item)
end

setCatalogSort#

Sets the sorting function sortFunction to be used in the catalog view. The provided sorting function can use logic based on Item info such as price or title. This function can only be called from a LocalScript.

Here are some examples for sorting the catalog:

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.setCatalogSort(function(a, b)
	return a.price < b.price
end)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.setCatalogSort(function(a, b)
	return a.price > b.price
end)

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.setCatalogSort(function(a, b)
	return if a.price == b.price then a.title < b.title else a.price < b.price
end)

setControlKeyCodes#

Configures the key and button values for interactions with the merch booth. The first parameter must be a MerchBooth.Controls enum and the second parameter a table containing the keys keyboard and/or gamepad with corresponding KeyCode enums.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.setControlKeyCodes(MerchBooth.Controls.ProximityPrompts, {
	keyboard = Enum.KeyCode.Q,
	gamepad = Enum.KeyCode.ButtonL1,
})

openMerchBooth#

Opens the merch booth window (if closed) and navigates to the catalog view. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(assetId)
end)
if not success then
	warn(errorMessage)
end

MerchBooth.openMerchBooth()

openItemView#

Navigates to the single item view of the given itemId, opening the merch booth window if it is currently closed. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	MerchBooth.openItemView(4819740796)
end

toggleCatalogButton#

Toggles on/off the catalog button on the right side of the screen. This is useful when implementing a custom button or limiting the merch booth's appearance to regions or proximity prompts. Can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.toggleCatalogButton(false)

isMerchBoothOpen#

Returns true if either the catalog or the item view is open. If the item view is open, the item's asset ID is returned as the second value. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local success, errorMessage = pcall(function()
	MerchBooth.addItemAsync(4819740796)
end)
if success then
	MerchBooth.openItemView(4819740796)

	local isOpen, itemId = MerchBooth.isMerchBoothOpen()
	print(isOpen, itemId)
end

closeMerchBooth#

Closes the merch booth window. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

MerchBooth.closeMerchBooth()

isMerchBoothEnabled#

This function may be used in tandem with setEnabled to check whether the merch booth is currently enabled or not. Can only be called from a LocalScript.

setEnabled#

Sets whether the entire merch booth is enabled or not. When disabled, this function removes the entire UI, including proximity prompts, and disconnects all events. This function can only be called from a LocalScript.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

local isEnabled = MerchBooth.isMerchBoothEnabled()
if isEnabled then
	MerchBooth.setEnabled(false)
end

Events#

itemAdded#

Fires when an item is added through addItemAsync. This event can only be connected in a Script.