Earning rules page

To provide customers with insights into how they can earn points through various activities, you can create an "Earning Rules" page within your mobile app. This page will display the earning rules applicable to the customer, including details about frequency bonuses and their progress toward meeting earning goals.

Accessing Earning Rules

The Earning Rules endpoint provides access to data specific to the customer, including their earning potential and the status of various earning activities. This endpoint will return details about the earning rules set up in your loyalty program.

How to render

Determine location

This view is location‑specific.

• If you pass a location, results are filtered to that location.

• If you do not pass one, Perkville will use a default location. To determine which location you're viewing, each item in the list of returned perks will include a loc_id parameter.

Display earning rules in the order returned

The endpoint returns a list in display order. Do not re‑sort.

Show the rule title and points

Use a list layout that shows the rule title on the left and points on the right (as shown in the screenshot).

Render any bonuses applicable to the perk

If a rule has frequency bonus progress, display their using a progress indicator (e.g., “2/6” or “6x / mo”) and a bonus points label. This can be rendered inline, or separately, as we show in the screenshot.

Render instant rewards

If a rule includes instant rewards, display them alongside the rule’s point value. Some rules have points, instant rewards, or both.

Do not show rules that are not returned

If a rule doesn’t appear in the Earning View, do not show it. Some perks are available in the Perk endpoint that are suppressed on purpose (bookkeeping perks, intentionally hidden by the business admin, etc).

Grouping earning rules by category

The Earning 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 rule’s category field (if present).

2. Use the Perk Categories endpoint to fetch category metadata (name, display order).

3. Group rules client‑side by category, and display uncategorized rules last.

Bonus category nuance

Bonuses (frequency, time, date range, etc) can have their own category that differs from the base earning rule. When rendering bonuses that have a category distinct from their parent rule, group them by their own category, not the parent rule’s category. If the bonus does not have a category, it should be rendered with the parent earning rule.