Levels

Levels can be one indicator of a user's engagement in your program. They can be used to indicate when a user reaches a milestone or accomplishes a goal. You define levels in one of the following ways:

Points - Assign levels automatically based on the user's point balance. When the user's lifetime balance reaches a certain threshold, the user graduates to the next level. If a user redeems points, their level is not affected since redemption changes their current balance not their lifetime balance. However, a user can level down if a mission reward is removed or their lifetime balance is debited. Note: A point transaction must occur for a user's level to change.
Custom - Assign levels manually via API calls. Custom levels are based on criteria defined entirely by your site. For example, your level criteria may be based on the user point balance, achievements, or other unrelated factors.

You can display levels in different ways. For example, if a new level unlocks new content on your site, you may want to display the user's level on every page (similar to displaying their user name and logged in status).

Ordering Levels

When using points based leveling, your levels automatically order by the points field. When using custom leveling, you can order your levels using the API. Level ordering determines the result of the /users/{userId}/levels method.

Note: For Custom levels, before a user is explicitly assigned a level they are auto-assigned to the first level in the level order. If you change the ordering and the first level changes, all users that haven't been assigned a level get the new first level. Anyone who was explicitly assigned a level always keeps the level they were assigned, even if you reorder the levels.