Documentação

English

Português
Español

English

Português
Español

Appearance

Rewards Club — Levels ​

Access prerequisites

  • Permission (module): viewRewardsProgram (to read) / manageRewardsLevels (to create/edit/delete/reorder)
  • License/Feature: REWARDS_CLUB
  • Menu container: GENERAL → group Rewards Club

What it is / when to use ​

Manages the club's levels (tiers) in a fully dynamic way: you create as many levels as you want, with a free name, threshold (entry threshold), color, icon, and a list of benefits. The order is defined by drag-and-drop. Each level can have a tier NFT generated inline.

Use it when designing the loyalty ladder (e.g.: Bronze → Silver → Gold → Diamond) and when adjusting thresholds/benefits over time.

Pre-conditions ​

  • Permission: viewRewardsProgram to read; manageRewardsLevels to edit (dual permission: CPM enum + dynamic module in the DB).
  • License/Feature: REWARDS_CLUB.
  • Dependencies from other screens: the Program defines the metric and the reference fiat — this changes how the threshold is displayed: in pts when the metric is POINTS, or in the reference currency when financial.

Step by step ​

  1. Go to the menu Rewards Club → Levels (/rewards-club/levels).
  2. The list shows levels in order; drag by handles to reorder (persists automatically).
  3. Click New (or click a level to edit) — opens the lateral drawer.
  4. Fill in the tier code, name, description, threshold, color, icon, and benefits.
  5. Save. To generate the level's NFT, use the Generate NFT button on the row.

Fields ​

FieldWhat it isRequired?System/backend effect
Tier (tier)Level code (free string, e.g.: GOLD)YesNormalized to UPPERCASE with _ in place of spaces. It is the level's key (together with the program). Cannot duplicate on creation.
Name (customName → name)Displayed level nameYesFriendly label for the tier.
Description (description)Descriptive textNoFree text.
Threshold (threshold → minThresholdFiat)Minimum threshold to enter the levelYesCompared against the program metric. Displayed in pts (POINTS metric) or in the reference currency (financial metric). Transmitted as a BigNumber string.
Color (badgeColor → colorHex)Badge color (hex)YesVisual color of the level; suggested palette in cycle.
Icon (iconName)Badge icon (Material Icons)NoQuick-picker with suggestions (trophy, medal, diamond…).
Benefits (benefits[])List of level benefitsNoLine-by-line editor. Lines in key: value format become structured benefits (e.g.: indicationBonusPercent: 5); others become a label.
Order (order → sortOrder)Level positionYes (managed)Defined by drag-and-drop; renumbered in multiples of 10 (10, 20, 30…) to ease future insertions.
Tier NFT (tierNftAssetId)NFT asset representing the levelNoundefined = not yet generated. The Generate NFT button creates the asset via tknLib (idempotent).

Actions and modals ​

  • Reorder (drag-and-drop): persists the new order via PATCH .../levels/reorder immediately (optimistic update; on error, reloads to undo).
  • Save level: PUT /v1/rewards-club/admin/levels/:tier. Requires step-up (password + MFA). Validates required tier, absence of duplicates on creation, and filled name.
  • Delete level: DELETE .../levels/:tier with step-up. Blocked if there are users in the tier — the backend responds ok=false + reason=USERS_IN_TIER + usersInTier, and the UI shows how many users prevent deletion.
  • Generate NFT: POST .../levels/:tier/generate-nft. Idempotent: if it already exists, returns alreadyExists=true and only links the assetId.

Business rules / cautions ​

Caution

  • It is not possible to delete a level that has users positioned in it — empty/migrate the users first. This protects the integrity of the tier engine.
  • The tier NFT must be locked for sale/resale (block_sell and block_resell) — it is a badge, not a tradable asset. The inline generation already creates the asset appropriately.
  • The threshold display depends on the Program metric: check there before defining thresholds (pts vs. fiat).

Irreversible

  • Generate NFT creates an on-chain asset via tknLib. The operation is idempotent (does not duplicate), but the created asset permanently represents the level — treat the tierNftAssetId as definitive for that tier.
  • Financial values: thresholds are transmitted as BigNumber strings — no rounding.

Examples ​

Scenario 1 — Financial ladder in BRL

Program with metric DEPOSIT_VOLUME, window LIFETIME, fiat BRL.

  1. Create Bronze (threshold 0), Silver (5000), Gold (20000), Diamond (100000).
  2. Define distinct colors/icons; add benefits (e.g.: indicationBonusPercent: 5 for Gold).
  3. Drag to ensure the order Bronze < Silver < Gold < Diamond.
  4. Generate the NFT for each level using the inline button.
Scenario 2 — Points-based ladder

Program with metric POINTS.

  1. Thresholds are now displayed in pts. Define, e.g.: Bronze 0, Silver 1000, Gold 5000.
  2. Ensure point-awarding missions exist in Missions so users can accumulate points.
Scenario 3 — Blocked deletion attempt

When deleting "Silver" with 37 users in the tier:

  1. The confirmation is accepted, but the backend returns USERS_IN_TIER with usersInTier=37.
  2. The UI informs that 37 users prevent deletion.
  3. Adjust thresholds/recompute to migrate the users and try again.