Introduction

 

The Badges API enables you to create badges on your website, and assign them to site members, either from your site dashboard, or from your live site. Badges are set up in your site dashboard. Wix does not provide preset badges.

Badges assigned to specific site members help them stand out from other members. You can use badges to create specific categories of members within your site.

With the Badges API, you can customize how badges are created and assigned, including, for example, automating creation of specific categories of members who will recieve a given badge, or delegating assignment of badges to site members themselves.

Learn more about member badges.

Terminology

  • Badge: a visible label to be displayed on a site member's profile. A badge has a name (mandatory), an icon, and a background color.

Before you begin

  • Badge permissions - badges can grant site members special permissions to access specific pages. You can set badge permissions in the Site Members area of the dashboard. Badge permissions can't be set in the API. Site members receive permissions once a permission-granting badge is assigned to them.

  • Member permissions cannot be managed via the badges API. You must set them in the site's dashboard.

Was this helpful?
Yes
No

Setup

To use the Badges API, install the @wix/members package using npm or Yarn:

Copy
1
npm install @wix/members

or

Copy
1
yarn add @wix/members

Then import { badges } from @wix/members:

Copy
1
import { badges } from '@wix/members'
Was this helpful?
Yes
No
assignBadge( )

Assigns a badge to site members.

The assignBadge() function returns a Promise that resolves when the specified badge is assigned to the specified members.

The badgeId parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function assignBadge(_id: string, memberIds: Array<string>): Promise<AssignBadgeResponse>
Method Parameters
_idstringRequired
Badge ID.
memberIdsArray<string>Required
List of member IDs to assign to the badge.
Returns
Return Type:Promise<AssignBadgeResponse>
Was this helpful?
Yes
No
createBadge( )

Creates a badge.

The createBadge() function returns a Promise that resolves to the newly created badge.

New badges do not have any badge permissions by default. You can set badge permissions from the Badges page in the Dashboard.

If backgroundColor or textColor are not specified, they default to "#796EFF" (purple) and "#FFFFFF" (white) respectively.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function createBadge(badge: Badge): Promise<Badge>
Method Parameters
badgeBadgeRequired
Badge to create.
Returns
Return Type:Promise<Badge>
Was this helpful?
Yes
No
deleteBadge( )

Deletes a badge.

The deleteBadge() function returns a Promise that resolves when the specified badge is deleted.

The badgeId parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function deleteBadge(_id: string): Promise<void>
Method Parameters
_idstringRequired
Badge ID.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
getBadge( )

Retrieves information about a badge.

The getBadge function returns a Promise that resolves when the badge information is retrieved.

The _id parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Read Badges
Learn more about permission scopes.
Copy
function getBadge(_id: string): Promise<Badge>
Method Parameters
_idstringRequired
Badge ID.
Returns
Return Type:Promise<Badge>
Was this helpful?
Yes
No
getMemberCountsPerBadge( )

Retrieves member count per badge.

The getMemberCountsPerBadge function returns a Promise that resolves when the member counts of each badge are retrieved.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Read Badges
Learn more about permission scopes.
Copy
function getMemberCountsPerBadge(): Promise<GetMemberCountsPerBadgeResponse>
Request
This method does not take any parameters
Returns
Return Type:Promise<GetMemberCountsPerBadgeResponse>
Was this helpful?
Yes
No
listBadges( )

Lists the badges.

The listBadges function returns a Promise that resolves when the badges are retrieved. Retrieves up to 1000 badges, given the requested paging. Default paging.limit is 100, paging.offset - 0.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Read Badges
Learn more about permission scopes.
Copy
function listBadges(options: ListBadgesOptions): Promise<ListBadgesResponse>
Method Parameters
optionsListBadgesOptions
Returns
Return Type:Promise<ListBadgesResponse>
Was this helpful?
Yes
No
listBadgesPerMember( )

Lists the badges assigned to each of the specified site members.

The listBadgesPerMember() function returns a Promise that resolves to a list of badge IDs associated with each of the specified members.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Read Badges
Learn more about permission scopes.
Copy
function listBadgesPerMember(memberIds: Array<string>): Promise<ListMembersBadgeIdsResponse>
Method Parameters
memberIdsArray<string>Required
List of members.
Returns
Return Type:Promise<ListMembersBadgeIdsResponse>
Was this helpful?
Yes
No
listMembersByBadge( )

Lists the IDs of all members assigned to a badge.

The listMembersByBadge() function returns a Promise that resolves to a list of member IDs assigned to the specified badge.

Retrieves up to 1000 site members who have a specified badge. Default paging.limit is 100, paging.offset - 0.

The _id parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

This function is not a universal function and runs only on the backend.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Read Badges
Learn more about permission scopes.
Copy
function listMembersByBadge(_id: string, options: ListMembersByBadgeOptions): Promise<ListMembersResponse>
Method Parameters
_idstringRequired
Badge ID.
optionsListMembersByBadgeOptions
Returns
Return Type:Promise<ListMembersResponse>
Was this helpful?
Yes
No
unassignBadge( )

Removes site members from an assigned badge.

The unassignBadge() function returns a Promise that resolves when the specified members are removed as holders of the specified badge.

The badgeId parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function unassignBadge(_id: string, memberIds: Array<string>): Promise<void>
Method Parameters
_idstringRequired
Badge ID.
memberIdsArray<string>Required
List of members to remove.
Returns
Return Type:Promise<void>
Was this helpful?
Yes
No
updateBadge( )

Updates a badge.

The updateBadge() function returns a Promise that resolves to the updated badge.

Only the properties passed in the BadgeInfo object will be updated. All other properties will remain the same.

Because the badge slug is based on the badge title, if you change title, slug is updated accordingly.

badgeId must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function updateBadge(_id: string, badge: UpdateBadge): Promise<Badge>
Method Parameters
_idstringRequired
Badge ID.
badgeUpdateBadgeRequired
Returns
Return Type:Promise<Badge>
Was this helpful?
Yes
No
updateBadgesDisplayOrder( )

Updates badges' display order.

The badgeId parameter must be an ID from your site's Members/Badges collection. Typically, you retrieve the ID from the collection using a query or through a dataset.

This function is not a universal function and runs only on the backend

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Badges
Learn more about permission scopes.
Copy
function updateBadgesDisplayOrder(badgeIds: Array<string>): Promise<UpdateBadgesDisplayOrderResponse>
Method Parameters
badgeIdsArray<string>Required
Ordered badge IDs.
Returns
Return Type:Promise<UpdateBadgesDisplayOrderResponse>
Was this helpful?
Yes
No