For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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. The response is sensitive to customer context, so use the appropriate authenticated user or server-side authorization when requesting a customer's available rewards.

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 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 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.

Last updated

Was this helpful?