> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/rewards-page.md).

# 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="https://2181708597-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSiE75SeColbiBVbet0NZ%2Fuploads%2FqKj4DlJCXGzoGoVBt9DR%2Frewards_Perkville_page.png?alt=media&#x26;token=4589fd1a-d570-4de6-b18e-dcb217a8a2ce" 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.

### Example request and authentication

The Redeeming Rules endpoint is a **GET** request to `/v2/redeeming/`. Use the authentication flow and scopes described in the [Perkville API documentation](https://www.perkville.com/developers/docs/v2/). The response is sensitive to customer context, so use the appropriate authenticated user or server-side authorization when requesting a customer's available rewards.

```http
GET /v2/redeeming/?business=<business_id>&location=<location_id> HTTP/1.1
Host: www.perkville.com
Authorization: Bearer <access_token>
```

Replace the placeholders with values for your application. Verify the supported location parameter, authorization method, and applicable customer context against the [Redeeming Rules API reference](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_redeeming_view_anchor) before implementing. Do not expose privileged server credentials in a mobile application.

### 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)

### External rewards and authenticated handoff

External rewards normally open the External Reward URL configured by the business.

For approved integrations and participating external reward providers, your backend can instead request a fresh, short-lived customer SSO launch URL when the customer taps the reward. This allows the provider to identify the authenticated customer and open the appropriate storefront without a second login.

Do not cache or reuse the SSO launch URL. Request a new link for each click.

See [Perkville → external reward provider customer handoff](https://docs.perkville.com/integrations/perkville-external-reward-provider-customer-handoff.md) for the full flow and security requirements.

### 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/integrations/integrating-perkville/integrating-your-app-with-perkville/rewards-page.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
