# Levels page

If the business is using [Levels](/features/levels.md), you can create a Levels or Tiers page in your app. This page lets customers view the available levels, their current level, and their progress toward the next one.

<figure><img src="/files/YY7ylTSfRgb8JwgoiZ7G" alt=""><figcaption></figcaption></figure>

### Accessing Levels

The [**Levels View** endpoint](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_levels_view_anchor) returns the data needed to render a customer-facing levels page.

Use **User Filters** to retrieve levels from the perspective of a specific customer, including their current status and progress. If you do not pass user filters, the endpoint returns levels from the perspective of a logged out customer.

### How to render

#### Display levels in the order returned

The endpoint returns levels in display order. Do not re-sort them in your app.

#### Show the level name and badge

For each level, display the level name and badge image when present.

#### Show the points required

Display the point threshold for each level.

#### Display the various perks/privileges in the levels

Perks will have a `can_redeem` flag. For current or previously earned levels, if that flag is true, make sure to provide a quick link that allows them to redeem that reward.

Privileges cannot be redeemed, and simply need to be displayed.

#### Highlight the customer's current level

When a customer is logged in, visually distinguish their current level. A highlighted row, badge, or status label works well.

#### Show progress toward the next level

When progress data is returned, show how far the customer is from the next level. A progress bar, ratio, or “points to go” label all work well.&#x20;

#### Handle logged-out views

Without user filters, or when filtering on a user that does not have a connection, show the available levels and their qualification thresholds. Do not show customer-specific progress or current-level status.

#### Reflect qualification rules exactly as returned

Level qualification can depend on the business setup, such as lifetime points, quarterly intervals, or yearly intervals. They may also be restricted to only active members. Be sure to use the values returned from the endpoint to clearly communicate these restrictions.

It would be good to specify whether the user needs to earn more points to achieve the next level, or if they need to earn points to maintain (or re-qualify for) their current level. This can be determined by using the `level_valid_until_dt` in combination with `level_validity_interval` and `points_until_this_level` (e.g. "Earn 50 more points to maintain Silver" or "Earn 100 more points to earn Gold").

#### Show restricted states when relevant

Some levels may require an active membership. If the response indicates the customer is not currently eligible, explain that in the UI.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.perkville.com/overview/integrations/integrating-perkville/integrating-your-app-with-perkville/levels-page.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.