> 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/tiers.md).

# Tiers

Designing tier levels and their conditions, showing members their tier and progress, handling invitation-only tiers, and keeping CRM in step.

Tiers group members into levels — Silver, Gold, Platinum — based on conditions such as units earned or money spent. Open Loyalty recalculates them from member activity; campaigns, rewards and visibility can depend on the tier. This page covers designing tiers, showing them, and the special case of a tier assigned by hand.

For the Admin Panel side, see [Tiers](https://help.openloyalty.io/gamification/tiers), [Adding tiers](https://help.openloyalty.io/gamification/tiers/adding-tiers), [Tier benefits](https://help.openloyalty.io/gamification/tiers/tier-benefits) and [Tier analytics](https://help.openloyalty.io/gamification/tiers/tier-analytics).

## Who does what

| Area                           | Responsibility                                                                                     |
| ------------------------------ | -------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | Tier sets, levels, conditions, downgrade rules and benefits; campaigns that depend on tiers        |
| **Integration layer**          | Reads tier and progress for the channels; assigns invitation-only tiers from back-office decisions |
| **Website / app**              | Current tier, progress to the next tier, benefits                                                  |
| **CRM / marketing automation** | Tier on the contact; upgrade, downgrade and "tier expiring" messages                               |

## Design decisions

| Decision                  | Options                                                                                                             | Recommendation                                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| What the tier is based on | Active units, total earned units, cumulative earned units, total spending, months since joining — combined with AND | Earned units or spending. Basing tiers on **active** units means redeeming points can drop a member's tier.                                                              |
| How many tier sets        | One, or several (per brand, per programme)                                                                          | One per audience. A programme can have up to five tier sets, three active at a time.                                                                                     |
| Downgrades                | Never, or on a schedule (e.g. registration anniversary)                                                             | Downgrade on a yearly schedule so members can see what they need to keep their tier.                                                                                     |
| Invitation-only tiers     | Reachable by conditions, or assigned by hand                                                                        | Give the top tier an unreachable threshold and assign it by hand — see below.                                                                                            |
| Changes after launch      | Edit tiers freely, or plan changes                                                                                  | Editing tiers doesn't recalculate existing members; each member is re-evaluated on their next activity or scheduled downgrade. Plan threshold changes with that in mind. |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create the tier set with its conditions and downgrade rules, then the levels and their benefits. Add any campaigns that depend on the tier (e.g. double points for Gold) and a **Member Tier Updated** campaign if an upgrade should give a bonus.
{% endstep %}

{% step %}

### Show the tier and progress

Read the member's tier sets with `GET /api/{storeCode}/member/{member}/tierSet` and the progress in one with `GET /api/{storeCode}/member/{member}/tierSet/{tierSet}` (current tier and what's needed for the next). Read the levels with `GET /api/{storeCode}/tierSet/{tierSet}/tiers` to show the ladder.
{% endstep %}

{% step %}

### Assign invitation-only tiers

`POST /api/{storeCode}/member/{member}/tier` locks the member in a tier: it isn't downgraded while the assignment lasts. Only a tier **above** the calculated one has an effect — a lower one is accepted and ignored. End it with `POST /api/{storeCode}/member/{member}/remove-manually-level`; normal rules apply again.
{% endstep %}

{% step %}

### Keep CRM in step

Subscribe to `CustomerLevelChanged` for upgrades and downgrades and `LevelWillExpire` for "keep your tier" reminders.
{% 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-79191b12b6f00ef87277ed0cda57b6ff83eea034%2Fig-tiers-flow.png?alt=media" alt="Automatic tiers: member activity reaches Open Loyalty, the tier is recalculated on the member&#x27;s next activity, and a CustomerLevelChanged webhook is sent; to show the tier, the integration layer reads the member&#x27;s progress in the tier set, for example Gold with 120 points to Platinum. Invitation-only tier: the back office invites a member; the integration layer assigns the tier by hand; Open Loyalty locks the member in it, only a tier above the calculated one has effect, and a Member Tier Updated campaign can give a one-time bonus; CustomerLevelChanged and CampaignEffectWasApplied webhooks follow. Removing the manual tier makes normal rules apply again." width="705"><figcaption><p>Automatic and invitation-only tiers</p></figcaption></figure>

{% hint style="info" %}
A tier upgrade — automatic or manual — raises the **Member Tier Updated** internal event, so a campaign on it can give a welcome bonus for the new tier. Limit it to once per member per tier so a member who drops and regains a tier isn't paid twice, if that's the intent.
{% endhint %}

## Go-live checklist

### Admin Panel

* [ ] Tier conditions use earned units or spending — not active units — unless redemptions are meant to affect tiers.
* [ ] Downgrade rules and their schedule are agreed and configured.
* [ ] Tier-dependent campaigns, rewards and visibility are tested at each level.
* [ ] Upgrade bonus campaigns have a per-member limit.

### Integration layer

* [ ] Tier and progress are read live from Open Loyalty.
* [ ] Invitation-only assignments come from an approved back-office process and can be removed.

### Website / app and CRM

* [ ] The member sees their tier, progress to the next tier and benefits.
* [ ] CRM updates the tier from `CustomerLevelChanged` and sends reminders from `LevelWillExpire`.

### Validation

* [ ] A test member moves up when crossing each threshold, on their next activity.
* [ ] Redeeming points doesn't lower the tier (unless designed to).
* [ ] A manual top-tier assignment locks the member and pays the bonus once.
* [ ] Removing the manual tier returns the member to their calculated tier.

## Key endpoints

* `GET /api/{storeCode}/member/{member}/tierSet` — [Get list of tier sets which member is assigned](https://help.openloyalty.io/api-reference/tier/get-list-of-tier-sets-which-member-is-assigned)
* `GET /api/{storeCode}/member/{member}/tierSet/{tierSet}` — [Return tier set member progress](https://help.openloyalty.io/api-reference/tier/return-tier-set-member-progress)
* `GET /api/{storeCode}/tierSet/{tierSet}/tiers` — [Get tiers list from a tier set](https://help.openloyalty.io/api-reference/tier/get-tiers-list-from-a-tier-set)
* `POST /api/{storeCode}/member/{member}/tier` — [Assign member to a tier](https://help.openloyalty.io/api-reference/member/assign-member-to-a-tier)
* `POST /api/{storeCode}/member/{member}/remove-manually-level` — [Remove manually assigned tier](https://help.openloyalty.io/api-reference/member/remove-manually-assigned-tier)

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

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

* Basing tiers on active units and then wondering why members drop a tier after redeeming.
* Expecting members to move immediately after changing thresholds: each is re-evaluated on their next activity.
* Assigning a lower tier by hand and expecting a downgrade — it has no effect.
* Forgetting to remove an invitation-only tier when the invitation ends.
  {% 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/tiers.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.
