---
title: "Player Level and XP Progress"
method: GET
path: "/levels/brand/{brandId}/player/{playerId}"
tags: ["Levels"]
---

# Player Level and XP Progress

`GET /levels/brand/{brandId}/player/{playerId}`

## Request

- Base URL: `https://opti-ls-api-us.optimove.net/api`
- URL: `https://opti-ls-api-us.optimove.net/api/levels/brand/{brandId}/player/{playerId}`
- Auth: none declared

Current level, XP progress, and rewards for reaching the next level. Use this to render the XP progress bar and level badge.

Draw the progress bar as `xpProgressInCurrentLevel / (xpForNextLevel - xpForCurrentLevel)`.

Reward references (`currentLevelRewards[].rewardId`, `nextLevelRewards[].rewardId`) resolve to the rewards catalog (match against `id`).

## Path parameters

- `brandId` string, uuid, required
- `playerId` string, required

## Response `200`

Player level state.

- PlayerLevel
  - `currentLevel` integer: Current level number (1-based).
  - `levelName` string: Display name for the current level (e.g. "Silver", "Gold").
  - `levelIcon` string, nullable: URL to the current level badge icon. `null` if no icon configured.
  - `nextLevelName` string, nullable: Display name for the next level. `null` if at max level.
  - `nextLevelIcon` string, nullable: URL to the next level badge icon. `null` if no icon or at max level.
  - `totalXp` integer: Cumulative XP earned across all levels.
  - `xpForCurrentLevel` integer: Total XP threshold required to reach the current level.
  - `xpForNextLevel` integer, nullable: Total XP threshold required to reach the next level. `null` if at max level.
  - `xpProgressInCurrentLevel` integer: XP earned since entering the current level. Use this to draw the progress bar: `progress / (xpForNextLevel - xpForCurrentLevel)`.
  - `maxLevel` integer: Highest level in the program.
  - `isMaxLevel` boolean: `true` when the player has reached the top level. Hide "next level" UI when this is `true`.
  - `currentLevelRewards` LevelReward[]: Rewards the player received for reaching the current level.
    - `id` string, uuid
    - `levelId` string, uuid
    - `rewardId` string, uuid: Look up in the rewards catalog by matching against `id`.
    - `amount` integer
    - `createdAt` string, date-time
  - `nextLevelRewards` LevelReward[]: Rewards the player will receive upon reaching the next level. Show as incentive.
    - `id` string, uuid
    - `levelId` string, uuid
    - `rewardId` string, uuid: Look up in the rewards catalog by matching against `id`.
    - `amount` integer
    - `createdAt` string, date-time
  - `claimableLevels` ClaimableLevel[]: Levels the player has reached but not yet claimed that carry rewards. Empty or omitted when nothing is claimable. Each entry drives a per-level "Claim" button. Call the claim-level-reward endpoint with the entry's `levelNumber` (and the active `levelConfigId` from the per-config endpoint) to grant the reward and remove the entry from this array.
    - `levelNumber` integer: The level number being claimed. Pass as `levelNumber` to the claim-level-reward endpoint.
    - `name` string: Display name of the level (e.g. "Bronze").
    - `levelIcon` string, nullable: URL to the level badge icon. `null` if no icon configured.
    - `rewards` LevelReward[]: Rewards attached to this level. `rewards[].rewardId` resolves to the rewards catalog `id`.
      - `id` string, uuid
      - `levelId` string, uuid
      - `rewardId` string, uuid: Look up in the rewards catalog by matching against `id`.
      - `amount` integer
      - `createdAt` string, date-time

## Other responses

- `404`: Resource not found (brand, player, mission, leaderboard, etc.).

---

[API](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api.md) - [All operations](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api/llms.txt) - [OpenAPI document](https://skmtc.dev/optimove/apis/optimove-loyalty-system-api/revisions/f174877a5fb7?raw)