> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snagsolutions.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Badges
> Create achievement badges to gamify your Web3 loyalty program. Set conditions based on rules, points, or other badges, and track user progress via the API.
## 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`](https://docs.snagsolutions.io/api-reference/badge/get-badges-all-or-by-id) 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`](https://docs.snagsolutions.io/api-reference/badge/create-new-badge) 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}`](https://docs.snagsolutions.io/api-reference/badge/update-badge-by-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}`](https://docs.snagsolutions.io/api-reference/badge/delete-badge-by-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`](https://docs.snagsolutions.io/api-reference/badge/reward-badge-for-account) 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`](https://docs.snagsolutions.io/api-reference/badge/revoke-badge-from-account) 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](https://docs.snagsolutions.io/api-reference/badge/reward-badge-for-account) or **upload a CSV file** with their wallet addresses.
## Related pages
Set up the loyalty program that powers badge conditions.
Display user rankings alongside badge achievements.
Let users redeem points for NFTs, auctions, and more.
Chain rules together to create multi-step badge journeys.