15 min read

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

BadgeService

Inherits from: Instance → Object

BadgeService provides information and functionality related to badges. Badges are used across the platform to recognize a player's achievements and activity. Upon awarding a badge to a player, it is added to their inventory and displayed on their profile page.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Methods

Name	Type / Returns	Description
BadgeService:AwardBadge	boolean	Award a badge to a player given the ID of each.
BadgeService:AwardBadgeAsync	boolean	Award a badge to a player given the ID of each.
BadgeService:CheckUserBadgesAsync	Array	Checks a list of badge IDs against a `UserId` and returns a list of badge IDs that the player owns.
BadgeService:GetBadgeInfoAsync	Dictionary	Fetch information about a badge given its ID.
BadgeService:GetUserBadgesAsync	Array	Checks a list of badge IDs against a `User` and returns, for each badge the player owns, its ID and the date it was awarded.
BadgeService:IsDisabled	boolean	Returns whether a given badge is disabled.
BadgeService:IsLegal	boolean	Determines if a given badge is associated with the current game.
BadgeService:UserHasBadge	boolean	Checks whether a user has the badge given the `Player.UserId` and the badge ID.
BadgeService:UserHasBadgeAsync	boolean	Checks whether a player has the badge given the `Player.UserId` and the badge ID.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

BadgeService:AwardBadge

Deprecated. Use AwardBadgeAsync() instead.

Award a badge to a player given the ID of each.

Parameters

Name	Type	Default	Description
userId	User		The `Player.UserId` of the user the badge is to be awarded to.
badgeId	int64		The ID of the badge to be awarded.

Returns

Type	Description
boolean	Boolean of `true` if the badge was awarded successfully.

Field	Value
tags	["Yields","Deprecated"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

BadgeService:AwardBadgeAsync

Grants a Player a badge with the UserId and the badge ID.

In order to successfully award a badge:

The player must be presently connected to the experience.
The player must not already have the badge (note that a player may delete an awarded badge from their profile and be awarded the badge again).
The badge must be awarded from a server script (a Script with RunContext of RunContext.Server or RunContext.Legacy) or a ModuleScript eventually required by one, not from a client script.
The badge must be awarded in a place that is part of the experience associated with the badge.
The badge must be enabled; check this using the IsEnabled property of the badge fetched through BadgeService:GetBadgeInfoAsync().

Rate limit is 50 + 35 * [number of users] per minute.

Parameters

Name	Type	Default	Description
userId	User		The `Player.UserId` of the user the badge is to be awarded to.
badgeId	int64		The ID of the badge to be awarded.

Returns

Type	Description
boolean	Boolean of `true` if the badge was awarded successfully.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

Code samples: View on Creator Hub (badges---awarding-a-badge).

BadgeService:CheckUserBadgesAsync

Checks a list of badge IDs against a UserId and returns a list of badge IDs that the player owns. This method supports batches of up to 10 badges; use BadgeService:UserHasBadgeAsync() for single badge lookups.

When called from a server script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked, and any badge IDs that are not associated with the requesting experience will not be included in the response (as if they were not owned).

For users that have recently been in the server, any badges for any experiences can be queried, no matter who created the badge or which experience it is used for.

In a client script (a LocalScript or a Script with RunContext of RunContext.Client), only the UserId of the local user whose client is running the script can be used.

Rate limit is 10 + 5 * [number of players] per minute in each server.

Parameters

Name	Type	Default	Description
userId	User		The `UserId` of the player to check for ownership of the specified badges.
badgeIds	Array		The list of IDs of the badges to check ownership of. Maximum length of 10.

Returns

Type	Description
Array	The list of badge IDs the given user owns out of the provided badge IDs. Empty if none of the provided badges are owned by the given user. Not guaranteed to be in the same order as the input list. Some badge IDs may be omitted if the user with the target `userId` has not recently been in the server and the badge IDs are not associated with the requesting experience.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

Code samples: View on Creator Hub (badges---checking-earned-badges-batch).

BadgeService:GetBadgeInfoAsync

This method fetches information about a badge given its ID and returns a dictionary with the following fields:

Key	Type	Description
`Name`	string	The name of the badge.
`Description`	string	The description of the badge.
`IconImageId`	int64	The asset ID of the image for the badge.
`IsEnabled`	boolean	Indicates whether the badge is available to be awarded.

This method takes a brief moment to load the information from Roblox; repeated calls will cache for a short duration.

Parameters

Name	Type	Default	Description
badgeId	int64		The badge ID of the badge whose information should be fetched.

Returns

Type	Description
Dictionary	A dictionary of information about the specified badge.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

Code samples: View on Creator Hub (getbadgeinfoasync).

BadgeService:GetUserBadgesAsync

Checks a list of badge IDs against a User and returns, for each badge the player owns, a dictionary containing the badge's ID and the date it was awarded. This method supports batches of up to 100 badges; use BadgeService:UserHasBadgeAsync() for single badge lookups.

Each entry in the returned list is a dictionary with the following fields:

Key	Type	Description
`BadgeId`	int64	The ID of the owned badge.
`AwardedDate`	DateTime	The date and time the badge was awarded to the user.

When called from a server script, any User can be used. If the user with the target User has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked, and any badge IDs that are not associated with the requesting experience will not be included in the response (as if they were not owned).

For users that have recently been in the server, any badges for any experiences can be queried, no matter who created the badge or which experience it is used for.

In a client script (a LocalScript or a Script with RunContext of RunContext.Client), only the User of the local user whose client is running the script can be used.

Rate limit is 10 + 5 * [number of players] per minute in each server.

Parameters

Name	Type	Default	Description
userId	User		The `User` of the player to check for ownership of the specified badges.
badgeIds	Array		The list of IDs of the badges to check ownership of. Maximum length of 100.

Returns

Type Description

Array A list of dictionaries, one for each badge the given user owns out of the provided badge IDs. Each dictionary contains a BadgeId and an AwardedDate. Empty if none of the provided badges are owned by the given user. Not guaranteed to be in the same order as the input list. Some badge IDs may be omitted if the user with the target User has not recently been in the server and the badge IDs are not associated with the requesting experience.

Type	Description
Array	A list of dictionaries, one for each badge the given user owns out of the provided badge IDs. Each dictionary contains a `BadgeId` and an `AwardedDate`. Empty if none of the provided badges are owned by the given user. Not guaranteed to be in the same order as the input list. Some badge IDs may be omitted if the user with the target `User` has not recently been in the server and the badge IDs are not associated with the requesting experience.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

Code samples: View on Creator Hub (badges---getting-earned-badges).

BadgeService:IsDisabled

Deprecated. This function is deprecated. Do not use it for new work. Instead, it can be checked by calling BadgeService:GetBadgeInfoAsync() and checking the IsEnabled field.

This function returns whether the badge with the given ID is marked disabled on the Roblox website. A badge can be disabled by its owner on its page on the Roblox website, in the settings sub-menu. When a badge is disabled, this function returns true and the badge can no longer be awarded. A badge may be quickly re-enabled through the same menu.

In Studio, a badge can only be tested if it is disabled. Calling this function with an enabled badge in Studio will return true and produce a warning "Sorry, badges can only be tested if they are disabled on Roblox game servers".

Note that even if a badge is enabled it may not necessarily be awardable (for example if it isn't associated with the current game).

Badges that are associated with special events are a common reason for a badge to be disabled. Often, it is easier to simply disable a badge instead of hard-coding a time check for when some event ends.

Parameters

Name	Type	Default	Description
badgeId	int64		The ID of the badge.

Returns

Type	Description
boolean	True if the specified badge is not available to be awarded.

Field	Value
tags	["Yields","Deprecated"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

BadgeService:IsLegal

Deprecated. This function is deprecated and will always return true. Do not use it for new work.

This function determines if a given badge is associated with the current game. It returns true if the badge is associated with the current game.

Badges can only be awarded from a place that is part of the game associated with the badge. This means, for example, a developer cannot award a badge associated with another developer's game.

Even if this returns true, a badge may still not be award-able. For example, it may be disabled.

Parameters

Name	Type	Default	Description
badgeId	int64		The badge ID of the badge.

Returns

Type	Description
boolean	True if the badge is associated with the current game.

Field	Value
tags	["Yields","Deprecated"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

BadgeService:UserHasBadge

Deprecated. This method has been superseded by BadgeService:UserHasBadgeAsync() which should be used for new work instead.

Checks and returns whether a Player owns a badge given their UserId and the badge ID. You can call the function from a server script or a ModuleScript eventually required by one. When calling the method from a client script (a LocalScript or a Script with RunContext of RunContext.Client), it only works for the local user whose client is running the script.

When called from a server script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked. If the requested badge ID is not associated with the requesting experience and the target user has not recently been in the server, the method behaves as if the badge is not owned.

For users that have recently been in the server, any badge for any experience can be queried, no matter who created the badge or which experience it is used for.

Parameters

Name	Type	Default	Description
userId	User		The user ID of the user.
badgeId	int64		The badge ID of the badge.

Returns

Type	Description
boolean	True if the user has the badge.

Field	Value
tags	["Yields","Deprecated"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

BadgeService:UserHasBadgeAsync

Checks and returns whether a Player owns a badge given their UserId and the badge ID. You can call this method from a server script or a ModuleScript eventually required by one. When calling this method from a client script (a LocalScript or a Script with RunContext of RunContext.Client), it only works for the local user whose client is running the script.

When called from a server script, any UserId can be used. If the user with the target user ID has not recently been in the server, only badge IDs that are associated with the requesting experience will be checked. If the requested badge ID is not associated with the requesting experience and the target user has not recently been in the server, the method behaves as if the badge is not owned.

For users that have recently been in the server, any badge for any experience can be queried, no matter who created the badge or which experience it is used for.

Rate limit is 50 + 35 * [number of players] per minute.

Parameters

Name	Type	Default	Description
userId	User		The `Player.UserId` of the player to check for ownership of the specified badge.
badgeId	int64		The badge ID of the badge whose ownership will be checked.

Returns

Type	Description
boolean	Indicates if the specified user has the specified badge.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["AssetManagement"]

Code samples: View on Creator Hub (badges---checking-earned-badges).

Properties

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.