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.

Accessing Redeemable Rewards

The Redeeming Rules endpoint 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, they may not be accessible from the Redeeming Rules endpoint 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.