Badges

This recipe explains how to create and manage badges in Snag Loyalty.

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.

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.

---

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.