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

    1. Define member group according to site owner's needs
    2. Get currently eligible members using other APIs
    3. Create badge using the Create badge endpoint
    4. 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

    1. Get all available badges on site, to display to the user for assignment, using List badges endpoint
    2. Select the permissioned, "staff only" badge from the list. The badge must already exist, created with permissions added by the site owner.
    3. Assign badge to selected members, based on user input, using the Assign badge to members endpoint
    4. 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.

Was this helpful?
Yes
No

Badge Object

Attributes
idstringRead-onlyformat GUID
Badge ID.

titlestring
Text displayed on the badge in the Wix UI.

descriptionstring
Badge description.

backgroundColorstringformat COLOR_HEX
Badge background color in hexadecimal RGB format. Uppercase letters only. Example: #FFFFFF.

textColorstringformat COLOR_HEX
Badge text color in hexadecimal RGB format. Uppercase letters only. Example: #C81B53.

iconstring
URL of the badge icon image. Recommended to use SVG image format as it is resolution independent and looks great at any scale.

permissionsEnabledboolean
Whether the badge has special permissions to access specific members-only pages. When true, members with the badge receive special permissions, and site contributors can manage badge permissions in the site dashboard. When false, members with the badge receive no special permissions.

slugstringRead-only
Slugified name. Used to represent the badge in a URL.

createdDatestringRead-onlyformat date-time
Date the badge was created.

updatedDatestringRead-onlyformat date-time
Date the badge was updated.
Was this helpful?
Yes
No

GetList Badges

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/members/v3/badges

Was this helpful?
Yes
No

PostCreate Badge

Developer Preview

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:
Manage Badges
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/members/v3/badges

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PatchUpdate Badge

Developer Preview

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:
Manage Badges
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/members/v3/badges/{badge.id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostQuery Badges

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/members/v3/badges/query

Was this helpful?
Yes
No

GetGet Badge

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/members/v3/badges/{id}

Was this helpful?
Yes
No

DeleteDelete Badge

Developer Preview

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:
Manage Badges
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/members/v3/badges/{id}

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

GetList Members By Badge

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/members/v3/badges/{id}/members

Was this helpful?
Yes
No

PostAssign Badge To Members

Developer Preview

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:
Manage Badges
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/members/v3/badges/{id}/members

Event TriggersThis method triggers the following events:
Was this helpful?
Yes
No

PostList Badges Per Member

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/members/v3/badges/members

Was this helpful?
Yes
No

GetGet Member Counts Per Badge

Developer Preview

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:
Read Badges
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/members/v3/badges/members/count

Was this helpful?
Yes
No

PatchUpdate Badges Display Order

Developer Preview

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:
Manage Badges
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/members/v3/badges/order

Was this helpful?
Yes
No

Badge Created

Developer Preview

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.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.badges.v3.badge.

slugstring
Event name. Expected created.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

createdEventobject
Event information.
Was this helpful?
Yes
No

Badge Updated

Developer Preview

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.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.badges.v3.badge.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Badge Deleted

Developer Preview

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.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.badges.v3.badge.

slugstring
Event name. Expected deleted.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

deletedEventstruct
Event information.
Was this helpful?
Yes
No

Badge Assigned

Developer Preview

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.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.badges.v3.badge.

slugstring
Event name. Expected badge_assigned.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No

Badge Unassigned

Developer Preview

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.

Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.badges.v3.badge.

slugstring
Event name. Expected badge_unassigned.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No