---
title: 'Create new badge'
description: 'This endpoint allows you to configure a new badge'
openapi: POST /api/loyalty/badges
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://docs.snagsolutions.io/llms.txt). Append `.md` to any page URL for its markdown version.

`POST /api/loyalty/badges`

`POST https://admin.snagsolutions.io/api/loyalty/badges`

This endpoint allows you to configure a new badge

## Authentication

- `apiKeyAuth` — apiKey in header: `X-API-KEY`

## Request body

- Content type: `application/json`
  - request body (object) — Schema for creating a new badge.
    - `organizationId` (string, uuid, required) — UUID of the organization (optional, converted to lowercase)
    - `websiteId` (string, uuid, required) — UUID of the website (optional, converted to lowercase)
    - `name` (string, required) — The name of the badge
    - `hideInUi` (boolean, default: false) — Whether to hide this badge in the user interface
    - `description` (string) — The description of the badge
    - `imageUrl` (string, uri, required) — The URL of the badge image
    - `rewards` (array) — Array of rewards granted when the badge is achieved
      - `items` (object)
        - `rewardType` (string, required, one of: points, multiplier, badge, token) — Type of reward (points or multiplier)
        - `loyaltyCurrencyId` (string, uuid) — UUID of the loyalty currency for this reward
        - `loyaltyCurrencyIds` (array) — Array of loyalty currency IDs for multiplier rewards (empty means all currencies)
          - `items` (string, uuid)
        - `amount` (number) — Points amount to reward (for points reward type)
        - `multiplier` (number) — Multiplier to reward (for multiplier reward type)
        - `isRetroactive` (boolean, default: false) — Whether the multiplier should be applied to the user's existing balance
    - `conditions` (array, required) — Array of conditions for the badge
      - `items` (object)
        - `type` (string, one of: rule, rules, points, section, level, api, badge, badges, csv) — The type of rule
        - `description` (string) — The description of the rule
        - `amount` (number) — The amount of the rule
        - `repeatCount` (number) — The number of times the rule should be repeated to fulfill the condition
        - `requiredCount` (number) — The number of rules that need to be fulfilled to satisfy the condition
        - `loyaltyRuleChainId` (string, uuid) — UUID of the loyalty rule chain (optional, converted to lowercase)
        - `loyaltyRuleIds` (array) — Array of UUIDs of the rules (optional, converted to lowercase)
          - `items` (string, uuid)
        - `loyaltyRuleGroupIds` (array) — Array of UUIDs of the rule group (optional, converted to lowercase)
          - `items` (string, uuid)
        - `loyaltyLeaderboardViewIds` (array) — Array of UUIDs of the Loyalty Leaderboard (optional, converted to lowercase)
          - `items` (string, uuid)
        - `loyaltyCurrencyIds` (array) — Array of UUIDs of the currency (optional, converted to lowercase)
          - `items` (string, uuid)
        - `loyaltyBadgeIds` (array) — Array of UUIDs of the badge (optional, converted to lowercase)
          - `items` (string, uuid)
        - `csvUrl` (string, uri) — URL of the CSV file (optional)
    - `csvFiles` (array)
      - `items` (object)
        - `src` (string, uri, required)
        - `name` (string)
        - `description` (string)

## Response 200

200
  - response (object) — Response returned upon successful creation of the badge.
    - `id` (string, uuid, required) — UUID of the badge (converted to lowercase)
    - `name` (string, required) — The name of the badge
    - `description` (string, required) — The description of the badge
    - `imageUrl` (string, uri, required) — The URL of the badge image
    - `hideInUi` (boolean, default: false) — Whether to hide this badge in the user interface
    - `loyaltyConditions` (array, required) — Array of conditions of the badge
      - `items` (object) — Schema for a loyalty condition rule.
        - `id` (string, uuid, required) — UUID of the condition (converted to lowercase)
        - `type` (string, required, one of: rule, rules, points, section, level, api, badge, badges, csv) — The type of the condition
        - `description` (string, required) — The description of the condition
        - `amount` (number, required) — The amount of the condition
        - `repeatCount` (number, required) — The repeat count of the condition
        - `requiredCount` (number, required) — The required count of the condition
        - `loyaltyRuleGroupId` (string, uuid, required) — UUID of the rule group (converted to lowercase)
        - `association` (array, required)
          - `items` (object)
            - loyaltyRule: … (nested further)
            - loyaltyBadge: … (nested further)
            - loyaltyRuleGroup: … (nested further)
            - loyaltyCurrency: … (nested further)
            - loyaltyLeaderboardView: … (nested further)
        - `loyaltyCurrencyId` (string, uuid, required) — UUID of the currency (converted to lowercase)
        - `csvUrl` (string, uri, required) — URL of the CSV file
        - `csvFiles` (array) — Array of CSV files associated with the condition
          - `items` (object)
            - id: … (nested further)
            - url: … (nested further)
            - name: … (nested further)
            - description: … (nested further)
    - `rewards` (array) — Array of rewards granted when the badge is achieved
      - `items` (object)
        - `id` (string, uuid, required) — UUID of the badge reward
        - `rewardType` (string, required, one of: points, multiplier, badge, token) — Type of reward (points or multiplier)
        - `loyaltyCurrencyId` (string, uuid, required) — UUID of the loyalty currency for this reward
        - `loyaltyCurrencyIds` (array) — Array of loyalty currency IDs for multiplier rewards (empty means all currencies)
          - `items` (string, uuid)
        - `amount` (number, required) — Points amount to reward (for points reward type)
        - `multiplier` (number, required) — Multiplier to reward (for multiplier reward type)
        - `isRetroactive` (boolean, required) — Whether the multiplier should be applied to the user's existing balance
    - `loyaltyBadgeUsers` (array) — Array of user badges
      - `items` (object)
        - `id` (string, uuid, required) — UUID of the user badge (converted to lowercase)
        - `userId` (string, uuid, required) — UUID of the user (converted to lowercase)
        - `websiteId` (string, uuid, required) — UUID of the website (converted to lowercase)
        - `organizationId` (string, uuid, required) — UUID of the organization (converted to lowercase)
        - `hideInUi` (boolean, default: false) — Whether to hide this badge in the user interface
        - `status` (string, required, one of: active, inactive, revoked) — The status of the badge
        - `loyaltyBadgeId` (string, uuid, required) — UUID of the badge (converted to lowercase)
        - `dismissedInUi` (boolean) — Whether the user has dismissed the badge in the UI
        - `user` (object) — User associated with the user badge
          - `id` (string, uuid, required) — UUID of the user (converted to lowercase)
          - `walletAddress` (string, required) — Wallet address of the user
        - `createdAt` (string, date-time, required) — The date and time the user badge was created
        - `completedAt` (string, date-time) — The date and time the user badge was granted
        - `updatedAt` (string, date-time, required) — The date and time the user badge was updated
    - `loyaltyRules` (array) — Array of loyalty rules associated with the badge
      - `items` (object)
        - `id` (string, uuid, required) — UUID of the loyalty rule (converted to lowercase)
        - `name` (string, required) — The name of the loyalty rule
    - `dataJobs` (array) — Array of data jobs associated with the badge
      - `items` (object)
        - `id` (string, uuid, required) — UUID of the data job (converted to lowercase)
        - `status` (string, required, one of: pending, processing, complete, failed, cancelled) — The status of the data job
        - `message` (string) — The message associated with the data job
        - `createdAt` (string, date-time, required) — The date and time the data job was created
        - `updatedAt` (string, date-time, required) — The date and time the data job was updated
    - `createdAt` (string, date-time, required) — The date and time the badge was created
    - `updatedAt` (string, date-time, required) — The date and time the badge was updated

## Response 403

403
  - response (object) — Schema for forbidden response
    - `message` (string, required) — Error message

## Response 500

500
  - response (object) — Schema for internal server error response
    - `success` (boolean, required) — Indicates operation success
    - `message` (string, required) — Error message
    - `debugInfo` (string) — Optional debug information


---

📦 **OpenAPI specs:** Every OpenAPI specification referenced by this documentation is available as a single download — https://docs.snagsolutions.io/api-specs.zip