---
title: 'Get badges (all or by id)'
description: 'This endpoint allows you to fetch badge(s) data.'
openapi: GET /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.

`GET /api/loyalty/badges` — query parameters: `organizationId`, `websiteId`, `badgeIds`, `walletAddress`, `userId`, `userGroupId`, `userGroupExternalIdentifier`, `startingAfter`, `limit`, `includeDeleted`

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

This endpoint allows you to fetch badge(s) data.

## Authentication

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

## Query parameters

- `organizationId` (string) — UUID of the organization (optional, converted to lowercase)
- `websiteId` (string) — UUID of the website (optional, converted to lowercase)
- `badgeIds` (string) — Array of badge IDs (converted to lowercase) to fetch
- `walletAddress` (string) — Wallet Address of the user, or array of wallet addresses.
- `userId` (string) — UUID of the user, or array of UUID.
- `userGroupId` (string) — UUID of the user group
- `userGroupExternalIdentifier` (string) — External identifier of the user group
- `startingAfter` (string) — UUID of the badge to start after (converted to lowercase)
- `limit` (integer) — Number of badges to fetch
- `includeDeleted` (boolean) — Include deleted badges in the response

## Response 200

200
  - response (object)
    - `data` (array, required)
      - `items` (object) — Response returned upon successful fetching of the badges.
        - `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: … (nested further)
            - type: … (nested further)
            - description: … (nested further)
            - amount: … (nested further)
            - repeatCount: … (nested further)
            - requiredCount: … (nested further)
            - loyaltyRuleGroupId: … (nested further)
            - association: … (nested further)
            - loyaltyCurrencyId: … (nested further)
            - csvUrl: … (nested further)
            - csvFiles: … (nested further)
        - `rewards` (array) — Array of rewards granted when the badge is achieved
          - `items` (object)
            - id: … (nested further)
            - rewardType: … (nested further)
            - loyaltyCurrencyId: … (nested further)
            - loyaltyCurrencyIds: … (nested further)
            - amount: … (nested further)
            - multiplier: … (nested further)
            - isRetroactive: … (nested further)
        - `loyaltyBadgeUsers` (array) — Array of user badges
          - `items` (object)
            - id: … (nested further)
            - userId: … (nested further)
            - websiteId: … (nested further)
            - organizationId: … (nested further)
            - hideInUi: … (nested further)
            - status: … (nested further)
            - loyaltyBadgeId: … (nested further)
            - progress: … (nested further)
            - dismissedInUi: … (nested further)
            - user: … (nested further)
            - createdAt: … (nested further)
            - completedAt: … (nested further)
            - updatedAt: … (nested further)
        - `loyaltyRules` (array) — Array of loyalty rules associated with the badge
          - `items` (object)
            - id: … (nested further)
            - name: … (nested further)
        - `dataJobs` (array) — Array of data jobs associated with the badge
          - `items` (object)
            - id: … (nested further)
            - status: … (nested further)
            - message: … (nested further)
            - createdAt: … (nested further)
            - updatedAt: … (nested further)
        - `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
    - `hasNextPage` (boolean, required) — Indicates if there is a next page of results

## 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