Badges
The Badges API enables site owners to create badges on their website or Wix App, and assign them to site members, either from their site dashboard, or from their live site. Badges are set up by site owners in their 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, third-party developers 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.
For an overview of badges, see 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.
Badge Permissions
Badges can grant site members special permissions to access specific pages.
Site owners 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.
Use cases
Auto assign badges for the most active members. A third party developer wants to create a loyalty program app that auto assigns badges to members, based on their activities.
-
Required information
- Retrieve member IDs from the Site members API, using the List Members endpoint to get a full list of all members.
- Select relevant members, based on e.g. activities, orders list / bookings etc. by looking up the member IDs in the stores API / bookings APIs):
- To select members with a long store order history, you may wish to retrieve all orders with the Query Orders endpoint, filtering by
buyerInfo.id
. Retrieving a list of all orders, e.g. with an empty query filter, may include buyers who are site contacts, but not site members. - To select members who actively book services, you may wish to use the Query Bookings endpoint and include the
contactId
of each member retrieved from the Site Members API.
-
Steps
- Define member group according to site owner's needs
- Get currently eligible members using other APIs
- Create badge using the Create badge endpoint
- Assign badge using the Assign badge to members endpoint
Allow site members to assign badges to other members. A third party developer wants to create a community in which members can assign badges to one another and see available badges. For example, a site admin member may want to give certain site members access to a permissioned, "staff only" page on their site.
-
Required information
- Member's details (Site members API)
-
Steps
- Get all available badges on site, to display to the user for assignment, using List badges endpoint
- Select the permissioned, "staff only" badge from the list. The badge must already exist, created with permissions added by the site owner.
- Assign badge to selected members, based on user input, using the Assign badge to members endpoint
- Show updated listing of member's badges using the List badges per member endpoint
Limitations
Member permissions themselves cannot be managed via the badges API. They must be set by the site owner in the site's dashboard.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves up to 1000 badges, given the requested paging.
Default paging.limit
is 100, paging.offset
- 0.
For more information, see
API Query Language: The Paging Section.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a new badge.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a badge's specified properties.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves up to 1000 badges, given the requested query options, paging, and sorting.
Default paging.limit
is 100, paging.offset
- 0.
For more information, see
API Query Language: The Paging Section.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a badge.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Deletes a badge.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves up to 1000 site members
who have a specified badge.
Default paging.limit
is 100, paging.offset
- 0.
For more details on how to use paging, see documentation
here.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Assigns a badge to the specified members. The members inherit the badge's permissions when they receive the badge, if applicable. Badge permissions are added to previous member permissions (they don't replace existing permissions).
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves badges assigned to the requested members.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves member count per badge.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates badges' display order.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a badge is created.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a badge is updated.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a badge is deleted.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a member receives a badge.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a member's badge is removed.