Skip to main content

​
Overview

The Badges feature in Snag Admin allows you to create and manage badges that users can earn by fulfilling specific condtions. These badges are displated on user profiles along with their progress towward unlocking them.
Snag admin badge creation form with conditions and reward settings
Users can earn badges by:
  • Completing specific rules or set of rules
  • Achieving a certain amount of loyalty points
  • Unlocking another badge or set of badges
  • Meeting any other custom conditions
Each badge displays a list of conditions and tracks user progress toward achieving them. The API provides real-time updates on user completion status, allowing users to see how close they are to earning a badge.
User profile displaying earned badges and progress toward unlocking them

​
Creating and Managing Badges

This recipe explains how to manage badges using the Snag API, including creating, updating and deleting badges but also assigning badges to users and revoking them.

​
Fetching Badges

The GET /api/loyalty/badges endpoint allows for fetching of loyalty badges created on your Snag account. This endpoint provides various filters to allow pagination. Badges are sorted by their creation date in descending order.

​
Example Request

Request 
{
  "organizationId": "your-organization-id",
  "websiteId": "your-website-id",
  "limit": 10
}
  • Note: for paginated requests be sure to add the startingAfter property to subsequent requests.

​
Example Response

{
  "data": [
    {
      "id": "b1b1b1b1-b1b1-b1b1-b1b1-b1b1b1b1b1b1",
      "name": "Example Badge",
      "description": "This is an example badge",
      "imageUrl": "https://example.com/image.png",
      "loyaltyConditions": [
        {
          "id": "c1c1c1c1-c1c1-c1c1-c1c1-c1c1c1c1c1c1",
          "type": "rule",
          "description": "Rule completion: Link Click",
          "amount": null,
          "repeatCount": null,
          "requiredCount": null,
          "loyaltyRuleGroupId": null,
          "association": [
            {
              "loyaltyRule": {
                "id": "r1r1r1r1-r1r1-r1r1-r1r1-r1r1r1r1r1r1",
                "name": "Link Click"
              },
              "loyaltyBadge": null,
              "loyaltyRuleGroup": null,
              "loyaltyCurrency": null,
              "loyaltyLeaderboardView": null
            }
          ],
          "loyaltyCurrencyId": null,
          "csvUrl": null
        }
      ]
    }
  ],
  "hasNextPage": "false"
}

​
Creating a Badge

The POST /api/loyalty/badges endpoint allows for creating a new badge on your Snag account. This endpoint requires the following parameters:
  • organizationId: Your organization ID
  • websiteId: Your website ID
  • name: The name of the badge
  • description: A description of the badge
  • imageUrl: The URL of the badge image
  • rules: An array of conditions that must be met to earn the badge

​
Updating a Badge

The POST /api/loyalty/badges/{id} endpoint allows for updating an existing badge on your Snag account. The id parameter is required to identify the badge to update. We only allow updating the name, description, and imageUrl of the badge. The reason for this is to prevent any changes that could affect the badge’s conditions and user progress.

​
Deleting a Badge

The DELETE /api/loyalty/badges/{id} endpoint allows for deleting an existing badge on your Snag account. The id parameter is required to identify the badge to delete.

​
Rewarding User with a Badge

The POST /api/loyalty/badges/{id}/reward endpoint allows for rewarding a user with a badge on your Snag account. The id parameter is required to identify the badge to reward, and either userId or walletAddress is required to identify the user to reward.

​
Revoking a Badge from a User

The POST /api/loyalty/badges/{id}/revoke endpoint allows to revoke a badge from a user on your Snag account. The id parameter is required to identify the badge to revoke, and either userId or walletAddress is required to identify the user to revoke.

​
Assigning Badges via CSV

For manual badge assignment, upload a CSV file containing wallet addresses of users who should receive a specific badge. The uploaded file should follow this format: 
walletAddress
0x1...abc
0x2...def
After upload, the system will process the file and assign the badge to the listed users.

​
Important Notes

This system provides a flexible way to reward user engagement and encourage participation through achievements. The Badge feature is only available to websites with active loyalty programs.
Badges are not retroactive. They only track user progress and grant rewards starting up to 24 hours before their creation.
If you want to reward users who had already met the badge conditions before the badge was created, you must manually assign the badge using the Reward Badge API or upload a CSV file with their wallet addresses.

Loyalty Overview

Set up the loyalty program that powers badge conditions.

Leaderboards

Display user rankings alongside badge achievements.

Rewards Shop

Let users redeem points for NFTs, auctions, and more.

Quest Chaining

Chain rules together to create multi-step badge journeys.