# Rewards page

To provide visibility into available rewards, you can create a Perks or Rewards page within your mobile app. This page will showcase the items or services that customers can redeem using their earned points.

<figure><img src="/files/vDlmrtmLExYJjm3rQJ07" alt="" width="371"><figcaption></figcaption></figure>

### Accessing Redeemable Rewards

The [**Redeeming Rules** endpoint](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_redeeming_view_anchor) provides access to the perks or rewards that customers can redeem. This endpoint will return details about available rewards tailored to the specific user. Please note that not all redeemable perks are visible or available to all users. While some perks may be retrievable from the [**Perk** endpoint](https://www.perkville.com/developers/docs/v2/#v2_resource_19_anchor), they may not be accessible from the [**Redeeming Rules** endpoint](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_redeeming_view_anchor) for a given user.

### Location filtering

This view is **location‑specific**.

* If you pass a location, rewards are filtered to that location.
* If you don’t pass one, Perkville uses a **default location**.
* If you use `all_locs=true`, the response includes rewards across all locations and `loc_id` will be null. This is not recommended unless the business is using Categories to categorize their rewards.

### What to always display for each reward

At minimum, show:

* **Title**
* **Points**
* **Description** (if present)
* **Image** (if present)

Additional fields you should display when present:

* **Required level** (`required_level`)
* **Custom attribute restrictions** (`valid_customer_attributes`)
* **Redemption limits** (`user_redemption_limit_info`)
* **Must redeem at home location** (`must_redeem_at_home_location`)

Other fields that should be displayed on the redemption confirmation page/modal

* **Redemption instructions** (if present)
* **Perk fine print** (if present)
* **Business fine print** (if present)

### When to disable the Redeem button

Use `can_redeem` as the primary gate. The Redeem button should be disabled when:

* `can_redeem = false`
* `user_redemption_limit_info.has_met_limit = true`
* The user does not have a connection to the business, in which case there should be no button displayed

In addition, always show the **reason** when you can infer it:

* **More points needed**: show how many more points they need
* **Level‑restricted**: show required level (`required_level`)
* **Custom attribute‑restricted**: show required attributes (`valid_customer_attributes`)
* **Redemption limit**: show next redemption date (`user_redemption_limit_info.next_redemption_opportunity`)
* **Home‑location‑only**: show “Redeem at home location” when `must_redeem_at_home_location = true`

### Restricted perks (level or custom attribute)

When a reward is restricted:

* **Level restriction**\
  Use `required_level` to display the minimum level needed.
* **Custom attribute restriction**\
  Use `valid_customer_attributes` to list the required attribute values.

These restrictions should appear directly in the reward card or detail view so the customer understands why the reward is not available.

### Grouping rewards by category

The Redeeming View response is not category‑filtered. If the business is making use of Categories, you'll want to group rewards by category in your UI:

1. Read each reward’s `category` field (if present).
2. Use the **Perk Categories** endpoint to fetch category metadata (name, display order).
3. Group rewards client‑side by category, and display uncategorized rewards last.


---

# 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/rewards-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.