---
title: LevelConfig
tags: [data-model, mongoose]
aliases: [Level, Loyalty Tier, ILevelConfig]
---

# LevelConfig

Admin-managed configuration of loyalty tiers. Each row defines one level (`level`, `name`, `nameEn`, point window via `minPoints` / `maxPoints`), the perks unlocked (`benefits.*`), and presentation details (`icon`, `color`, `order`). The `User.points.level` field is resolved against this collection.

> [!note] Source
> `backend/src/models/LevelConfig.ts:24` — schema definition
> `backend/src/models/LevelConfig.ts:93` — model export

## Schema

| Field | Type | Required | Default | Validation | Index | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `level` | Number | yes | — | — | unique | Numeric level (1, 2, 3, ...). |
| `name` | String | yes | — | — | — | Local language name. |
| `nameEn` | String | yes | — | — | — | English name. |
| `minPoints` | Number | yes | `0` | — | yes | Inclusive lower bound. |
| `maxPoints` | Number | no | — | — | — | Inclusive upper bound (open if omitted). |
| `benefits.discountPercent` | Number | no | `0` | — | — | Percentage discount unlocked. |
| `benefits.freeShipping` | Boolean | no | `false` | — | — | Free shipping perk. |
| `benefits.prioritySupport` | Boolean | no | `false` | — | — | Priority support perk. |
| `benefits.specialOffers` | Boolean | no | `false` | — | — | Exclusive offers perk. |
| `icon` | String | no | `solar:medal-star-bold` | — | — | Icon identifier. |
| `color` | String | no | `#94a3b8` | — | — | Display color. |
| `order` | Number | yes | — | — | yes | Display order. |
| `isActive` | Boolean | no | `true` | — | yes | Active flag. |
| `createdAt` | Date | auto | — | — | — | Mongoose timestamp. |
| `updatedAt` | Date | auto | — | — | — | Mongoose timestamp. |

## Virtuals

None defined.

## Indexes

Defined at `backend/src/models/LevelConfig.ts:89-91`. Plus the implicit unique index on `level`:

- `{ minPoints: 1 }`
- `{ order: 1 }`
- `{ isActive: 1 }`

## Pre/Post Hooks

None declared.

## Instance Methods

None defined.

## Static Methods

None defined.

## Relationships

- **References**: none.
- **Referenced by**: indirectly by [[User]] (`points.level`) and [[PointTransaction]] (`metadata.levelBefore` / `metadata.levelAfter`).

## State Transitions

```mermaid
stateDiagram-v2
    [*] --> active
    active --> inactive : admin disables
    inactive --> active : admin re-enables
```

## Common Queries

```ts
// All active levels (ordered)
LevelConfig.find({ isActive: true }).sort({ order: 1 });

// Resolve a point total to a level
LevelConfig.findOne({
  isActive: true,
  minPoints: { $lte: points },
  $or: [{ maxPoints: { $gte: points } }, { maxPoints: { $exists: false } }],
}).sort({ minPoints: -1 });

// Fetch by level number
LevelConfig.findOne({ level });
```

Related: [[User]], [[PointTransaction]].