> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/badges.md).

# Badges

Recognising members with badges: designing badge types, granting them from campaigns and challenges, using them in rules, and showing earned and locked badges.

A badge recognises something a member did or is — "First purchase", "Explorer", "Early adopter". Campaigns and challenges grant them automatically; your support team can also grant them by hand. Badges can be shown in the member's profile and used as conditions in other rules.

For the Admin Panel side, see [Creating badges](https://help.openloyalty.io/gamification/badges/creating-badges), [Using badges in campaigns](https://help.openloyalty.io/gamification/badges/using-badges-in-campaigns) and [Granting badges to members](https://help.openloyalty.io/gamification/badges/granting-badges-to-members).

## Who does what

| Area                           | Responsibility                                                                                         |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Admin Panel**                | Badge types (name, permanent system code); "grant badge" effects on campaigns and challenge milestones |
| **Integration layer**          | Reads earned badges and badge types for the channels; grants badges from back-office tools if needed   |
| **Website / app and CMS**      | Badge images and copy, keyed by system code; earned and locked states                                  |
| **CRM / marketing automation** | "You earned a badge" messages from webhooks                                                            |

## Design decisions

| Decision              | Options                                             | Recommendation                                                                                                                      |
| --------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| System codes          | Free text, or a naming scheme                       | A scheme you can read in a year: `{area}_{name}_{level}` (e.g. `scan_explorer_2`). The system code can't be changed after creation. |
| Images and copy       | In Open Loyalty, or in your CMS                     | Badge types have no image field. Keep images and copy in your CMS, keyed by system code.                                            |
| One-off or repeatable | Granted once, or counted each time                  | Repeatable badges count up (`completedCount`); decide per badge whether the UI shows the count.                                     |
| Levels                | One badge with a count, or one badge type per level | One type per level (bronze, silver, gold) when each level has its own image or reward.                                              |
| Badges in rules       | Display only, or also conditions                    | Use a badge as a "has done this before" flag — e.g. give a welcome reward only if the member has no *Welcome* badge yet.            |

## Recommended flow

{% stepper %}
{% step %}

### Create the badge types

Create each badge type in the Admin Panel with its system code. Add matching images and copy in your CMS under the same code.
{% endstep %}

{% step %}

### Grant them from rules

Add a **grant badge** effect to the campaign or challenge milestone that should award it. For one-off grants by support, use the Admin Panel or `POST /api/{storeCode}/member/{member}/badge`.
{% endstep %}

{% step %}

### Show earned and locked badges

Read the member's badges with `GET /api/{storeCode}/member/{member}/badge` (system code, name, `completedCount`, dates) and all badge types with `GET /api/{storeCode}/badge-type` (cache it). Badge types the member hasn't earned are shown as locked.
{% endstep %}

{% step %}

### Message the member

Use `CampaignEffectWasApplied` to announce a new badge. For the latest badges on a dashboard, read member history type `BadgeCompleted`.
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-b74dbb43c1e5c0bc6eea1f6d75a4a11c61c636e0%2Fig-badges-flow.png?alt=media" alt="Earn: member activity reaches Open Loyalty; a campaign or challenge rule matches and its grant badge effect increases the badge&#x27;s completed count; a CampaignEffectWasApplied webhook lets CRM send a badge message. Display: the channel asks for the member&#x27;s badges; the integration layer reads the member&#x27;s badges with system code, name and count, and the cached list of all badge types to show unearned ones as locked; the channel takes images and copy from the CMS by system code." width="728"><figcaption><p>Earning and displaying badges</p></figcaption></figure>

{% hint style="info" %}
Deactivating a badge type stops new grants. If a campaign uses that badge in a condition or effect, review the campaign first — deactivation can break its logic.
{% endhint %}

## Go-live checklist

### Admin Panel

* [ ] Every badge type follows the system-code scheme.
* [ ] Every badge that should be earned automatically is granted by a campaign or challenge.
* [ ] Campaigns that use a badge as a condition are tested with and without the badge.

### Integration layer and CMS

* [ ] Every system code has an image and copy in the CMS — and a fallback for codes it doesn't know.
* [ ] Badge types are cached and refreshed when new badges are added.

### Website / app

* [ ] Earned and locked badges are shown; repeatable badges show their count if intended.

### Validation

* [ ] Each badge is granted by the activity it describes, and only by it.
* [ ] A badge granted by hand appears in the profile and in history.

## Key endpoints

* `GET /api/{storeCode}/member/{member}/badge` — [Return member badges status](https://help.openloyalty.io/api-reference/badge/return-member-badges-status)
* `GET /api/{storeCode}/badge-type` — [Return badge types list](https://help.openloyalty.io/api-reference/badge/return-badge-types-list)
* `POST /api/{storeCode}/member/{member}/badge` — [Add badge to member](https://help.openloyalty.io/api-reference/badge/add-badge-to-member)
* `PUT /api/{storeCode}/member/{member}/badge/{badgeType}` — [Update completed count for member badge](https://help.openloyalty.io/api-reference/badge/update-completed-count-for-member-badge) (corrections, migration)

**Webhooks:** [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied)

{% hint style="warning" %}
**Common pitfalls**

* Choosing system codes in a hurry — they're permanent.
* Expecting a badge image from the API: keep images in your CMS.
* Showing only earned badges, so members can't see what's left to collect.
* Deactivating a badge that a campaign condition still checks.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/badges.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
