18 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

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.

Note

To offer assets created by third parties in the merch booth, make sure Allow Third Party Sales is enabled from the Security section of Studio's Experience Settings window. If this setting is disabled, you will not be able to sell UGC assets created by other users.

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.

   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.

   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.

   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

Note

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.

   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.

   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.

   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.

   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.

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

   

Block to detect when players approach the front of the shop counter

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

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

   

3. Insert a new LocalScript under StarterPlayerScripts.

   

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

   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.

Note

If a player has opened an item view through a proximity prompt, it automatically closes when the player moves further away from the prompt object than its activation distance. If you want to keep the booth open regardless of the player's distance from the prompt, set closeWhenFarFromPrompt to false in a configure call.

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

configure(config: table)

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

Appearance

Proximity Prompts

Behavior

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

addItemAsync(assetId: number, productType: InfoType, hideFromCatalog: boolean)

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.

Note

This function can only be called from a Script and it performs an asynchronous network call that may occasionally fail. As shown below, it's recommended that it be wrapped in LuaGlobals.pcall() to catch and handle errors.

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

getItems(): table

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

removeItem(assetId: number)

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

addProximityButton(adornee: BasePart|Model|Attachment, assetId: number)

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.

Note

When implementing proximity prompts, you may want to remove the catalog button to eliminate its usage in opening the booth.

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

removeProximityButton(adornee: BasePart|Model|Attachment)

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

setCatalogSort(sortFunction: function): boolean

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

setControlKeyCodes(control: MerchBooth.Controls, keyCodes: table)

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

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

openItemView(itemId: number)

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

toggleCatalogButton(enabled: boolean)

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

isMerchBoothOpen(): Tuple

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

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

isMerchBoothEnabled(): boolean

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

setEnabled(enabled: boolean)

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.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

merchBoothClosed

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

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

catalogViewOpened

Fires when the catalog view is opened.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

catalogViewClosed

Fires when the catalog view is closed.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

itemViewOpened

Fires when the item detail view is opened.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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

itemViewClosed

Fires when the item detail view is closed.

local ReplicatedStorage = game:GetService("ReplicatedStorage")

local MerchBooth = require(ReplicatedStorage.MerchBooth)

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