Loyalty Program
Related sections: VIP Program in the Player Cabinet and program management.
Complete player program
loyaltyProgram
The operation returns me.loyaltyProgram: calculated progress for the current player and the complete published project structure. Names and descriptions are returned as displayNames and descriptions arrays, so the client first selects an exact locale match and then the project's primary language.
Exchange example
{
"documentId": "loyaltyProgram",
"variables": {}
}
{
"data": {
"me": {
"loyaltyProgram": {
"progress": {
"active": true,
"programEnabled": true,
"progressMode": "rolling_window",
"progressState": "active",
"currentProgress": "7619.000000",
"pendingProgress": "1500.000000",
"lifetimeProgress": "7619.000000",
"currentLevelId": "01910000-0000-7000-8000-000000000105",
"nextLevelId": "01910000-0000-7000-8000-000000000106",
"cycle": {
"id": "01910000-0000-7000-8000-000000000201",
"startsAt": "2026-08-01T00:00:00.000000Z",
"endsAt": "2026-08-31T23:59:59.999999Z",
"frozenUntil": null
},
"forecast": {
"projectedProgress": "1119.000000",
"projectedLevelId": "01910000-0000-7000-8000-000000000102",
"requiredToRetain": "4881.000000",
"downgradeAt": "2026-09-04T18:00:00.000000Z",
"frozenUntil": null,
"expiringContributions": [
{
"ledgerEntryId": "01910000-0000-7000-8000-000000000301",
"progress": "6500.000000",
"expiresAt": "2026-09-04T18:00:00.000000Z"
}
]
}
},
"displayMode": "grouped",
"colors": [
{
"id": "01910000-0000-7000-8000-000000000401",
"displayNames": [
{
"locale": "en",
"text": "Sapphire"
},
{
"locale": "ru",
"text": "Сапфир"
}
],
"hexColor": "#4680FF",
"cssClass": null,
"sortOrder": 10
}
],
"tiers": [
{
"id": "01910000-0000-7000-8000-000000000501",
"code": "knight",
"displayNames": [
{
"locale": "en",
"text": "Knight"
},
{
"locale": "ru",
"text": "Рыцарь"
}
],
"descriptions": [
{
"locale": "en",
"text": "Second program tier"
}
],
"imageReference": "/data/project/1/vip/knight.webp",
"colorId": "01910000-0000-7000-8000-000000000401",
"sortOrder": 20,
"enabled": true
}
],
"levels": [
{
"id": "01910000-0000-7000-8000-000000000105",
"tierId": "01910000-0000-7000-8000-000000000501",
"colorId": "01910000-0000-7000-8000-000000000401",
"code": "knight-2",
"displayNames": [
{
"locale": "en",
"text": "Knight II"
},
{
"locale": "ru",
"text": "Рыцарь II"
}
],
"descriptions": [],
"imageReference": "/data/project/1/vip/knight-2.webp",
"minimumProgress": "6000.000000",
"stageOrder": 2,
"rewardsEnabled": true,
"enabled": true,
"benefits": [
{
"key": "top-up-bonus",
"benefitKind": "TOP_UP_BONUS",
"valueKind": "PERCENTAGE",
"numericValue": "7.000000",
"aggregation": "MAX",
"scopeMode": "PROJECT",
"displayNames": [
{
"locale": "en",
"text": "Top-up bonus"
}
],
"descriptions": [],
"gameServerIds": [],
"resourceCategories": [],
"icon": {
"kind": "CSS_CLASS",
"reference": "ti ti-sparkles"
},
"configuration": {},
"enabled": true,
"sortOrder": 10,
"availability": "AVAILABLE"
}
],
"rewards": [
{
"key": "knight-2-items",
"rewardKind": "GAME_ITEM_BUNDLE",
"displayNames": [
{
"locale": "en",
"text": "Knight bundle"
}
],
"descriptions": [],
"imageReference": "/data/project/1/vip/rewards/knight-2.webp",
"serverScope": "SELECTED_GAME_SERVERS",
"gameServerIds": [
1
],
"enabled": true,
"sortOrder": 10,
"availability": "AVAILABLE",
"components": [
{
"componentKind": "GAME_ITEM",
"resourceReference": "57",
"quantity": "250000",
"enchantLevel": 0,
"payload": {},
"sortOrder": 10
}
]
}
]
}
],
"currentLevel": {
"id": "01910000-0000-7000-8000-000000000105"
},
"nextLevel": {
"id": "01910000-0000-7000-8000-000000000106"
}
}
}
}
}
Progress and forecast
LoyaltyProgress contains:
| Field | Type | Description |
|---|---|---|
active | Boolean! | The player currently receives program effects |
programEnabled | Boolean! | The program is published and enabled |
progressMode | LoyaltyProgressMode! | Period calculation mode |
progressState | LoyaltyProgressState! | Current progress state |
currentProgress | String! | Confirmed progress in the active period |
pendingProgress | String! | Amount awaiting confirmation |
lifetimeProgress | String! | Parallel lifetime progress |
currentLevelId | ID | Current level |
nextLevelId | ID | Next level |
cycle | LoyaltyProgressCycle | Active-cycle and freeze boundaries |
forecast | LoyaltyProgressForecast! | Downgrade and expiring-contribution forecast |
Modes: lifetime, personal_cycle, calendar_month, rolling_window, season. States: inactive, active, frozen, grace. unspecified is a defensive contract state and must not be displayed as a user-facing label.
Every forecast.expiringContributions entry contains the progress-ledger identifier, exact amount, and expiry timestamp. requiredToRetain is the amount required to keep the current level after the projected change.
Program structure
displayMode = groupedgroups levels undertiers.displayMode = flatrenderslevelsas standalone ranks.colorsis the published palette referenced by levels and tiers.currentLevelandnextLevelcontain identifiers of objects inlevels; the client does not derive a level from thresholds.minimumProgress,numericValue, progress amounts, and quantities are strings to preserve exact decimal representation.
Benefits
LoyaltyProgramBenefit describes a displayable level rule:
| Field | Purpose |
|---|---|
benefitKind | Supported effect type |
valueKind | PERCENTAGE, MULTIPLIER, WHOLE_NUMBER, or CONFIGURATION |
numericValue | Exact numeric value, or null for a configuration type |
aggregation | MAX, SUM, or REPLACE |
scopeMode | PROJECT, ALL_GAME_SERVERS, or SELECTED_GAME_SERVERS |
gameServerIds | Servers included by selected-server scope |
resourceCategories | Optional operation-category restriction |
availability | Effective availability of the connected effect |
Benefit types: TOP_UP_BONUS, SHOP_DISCOUNT, REFERRAL_REWARD_MULTIPLIER, MARKET_FEE_DISCOUNT, GAME_ACCOUNT_LIMIT, LINKED_ACCOUNT_LIMIT, PROMO_ATTEMPTS, BONUS_CODE_BALANCE_MULTIPLIER, SUPPORT_PRIORITY, PROFILE_COSMETIC, CUSTOM.
availability is AVAILABLE, DISABLED, NOT_CONFIGURED, or UNAVAILABLE. An unavailable benefit remains visible in the structure and comparison, but the client must not promise that it will be applied.
Use the published values to display the current level's benefits.
Rewards
LoyaltyProgramReward describes a level reward rule and its display state. Supported kinds are GAME_ITEM, GAME_ITEM_BUNDLE, ENTITLEMENT, and CUSTOM_DELIVERY.
components contains typed contents:
GAME_ITEM- item identifier, quantity, and optional enchantment level;ENTITLEMENT- registered entitlement;CUSTOM_RESOURCE- resource from a connected integration with a typed payload.
Delivery scope is ALL_GAME_SERVERS or SELECTED_GAME_SERVERS. Reprocessing the same level achievement cannot create another delivery in the same cycle.
Errors
The me field requires an authenticated session. Temporary calculation failure returns a GraphQL error; offer to retry later.