Merch Booth

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

Module Usage

Installation

To use the MerchBooth module in an experience:

1. From the View tab, 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 Dev Modules 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 ServerScriptService. Upon running the experience, the module will distribute itself to various services and 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.

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

   

Adding 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.

   Script - Add Avatar Assets
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

   Script - Add Avatar Assets
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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

   This example uses assets owned by the Roblox account, but a thriving marketplace of incredible community-made assets is available here.

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.

   Script - Add Passes
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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 experience.

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

   

4. Click the ⋯ button for a pass and select Copy Asset ID.

   

5. Paste each copied ID into a comma-delimited list within the items table and include Enum.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.

   Script - Add Passes
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

   Script - Add Developer Products
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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 experience.

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

   

4. Click the ⋯ button for a product and select Copy Asset ID.

   

5. Paste each copied ID into a comma-delimited list within the items table and include Enum.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.

   Script - Add Developer Products
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

   LocalScript - Custom Catalog Button
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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 experience 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, or Studio's Tag Editor, 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 experience. Also disable its CanCollide and CanQuery properties so that objects do not physically collide with it and raycasts do not detect it.

   

   

4. Insert a new LocalScript under StarterPlayerScripts.

   

5. 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.

   LocalScript
   local Players = game:GetService("Players")
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   local CollectionService = game:GetService("CollectionService")
   
   local MerchBooth = require(ReplicatedStorage:WaitForChild("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-experience 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.

Changing 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.

LocalScript - ConfigureMerchBooth
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

LocalScript - ConfigureMerchBooth
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

LocalScript - ConfigureMerchBooth
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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 experience. assetId is the item's asset ID, productType is the item's Enum.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.

Script - Add Avatar Assets
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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

Script - Add Passes
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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

Script - Add Developer Products
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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:

Price Low-to-High
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

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

Price High-to-Low
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

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

Price Low-to-High & Alphabetical
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage:WaitForChild("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 Enum.KeyCode enums.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("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.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemAdded:Connect(function(assetId, itemInfo)
	print("Item added with asset ID of", assetId)
	print(itemInfo)
end)

itemRemoved

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

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemRemoved:Connect(function(assetId)
	print("Item removed with asset ID of", assetId)
end)

merchBoothOpened

Fires when either the catalog or item detail view are opened.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.merchBoothOpened:Connect(function()
	print("Booth view opened")
end)

merchBoothClosed

Fires when either the catalog or item detail view are closed.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.merchBoothClosed:Connect(function()
	print("Booth view closed")
end)

catalogViewOpened

Fires when the catalog view is opened.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.catalogViewOpened:Connect(function()
	print("Catalog view opened")
end)

catalogViewClosed

Fires when the catalog view is closed.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.catalogViewClosed:Connect(function()
	print("Catalog view closed")
end)

itemViewOpened

Fires when the item detail view is opened.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemViewOpened:Connect(function()
	print("Item view opened")
end)

itemViewClosed

Fires when the item detail view is closed.

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

local MerchBooth = require(ReplicatedStorage:WaitForChild("MerchBooth"))

MerchBooth.itemViewClosed:Connect(function()
	print("Item view closed")
end)