> 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/earning-rules-page.md).

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

<figure><img src="https://2181708597-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSiE75SeColbiBVbet0NZ%2Fuploads%2Fak8PkvpwTAmcna5gkkqt%2Fearning_rules_Perkville_page.png?alt=media&#x26;token=f76f432c-227c-407a-9af0-22b1047bd0a0" alt="" width="370"><figcaption></figcaption></figure>

### Accessing Earning Rules

The [**Earning Rules** endpoint](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_earning_view_anchor) 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.

### Example API request

Use the **GET** endpoint `/v2/earning/` with the business ID and, when you want a specific location's rules, the `loc_id` filter. The API reference documents `view_as_user=true` for showing earning rules from the perspective of the authenticated customer.

```bash
curl 'https://api.perkville.com/v2/earning/?business=2&loc_id=1&view_as_user=true' \
  -H 'Authorization: Bearer YOUR_CUSTOMER_ACCESS_TOKEN'
```

Replace the example business ID, location ID, and token with actual values. The token must represent the relevant customer when requesting their own earning view. For a mobile app, use the supported OAuth authorization-code / PKCE flow rather than embedding a client secret in the application.

The endpoint requires an applicable scope: `PUBLIC`, `USER_CUSTOMER_INFO`, or `ADMIN_CUSTOMER_INFO`. The `PUBLIC` scope returns a logged-out perspective; `USER_CUSTOMER_INFO` with `view_as_user=true` permits the authenticated user's perspective. If no `loc_id` is specified, Perkville uses the user's primary location or the business's primary location.

See the [Earning View API reference](https://www.perkville.com/developers/docs/v2/#v2_rewards_program_earning_view_anchor) for current filters, required permissions, and response fields.

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

For frequency bonuses, `frequency` can return `DAILY` in addition to the existing frequency values. The `/v2/frequency-bonus-progress/` response also includes `period_start_date` for each progress row.

For daily bonuses, use `period_start_date` to identify the progress period rather than assuming there will always be only one row for a customer and bonus. If a business spans time zones, adjacent daily periods can both be returned because the current local date may differ by location.

See [Frequency bonus](https://docs.perkville.com/features/earning-rules/promotions-and-bonus-earnings/frequency-bonus.md) for the business-facing configuration options.

#### Render time bonuses with structured time periods

For time bonuses, the Earning Rules response includes both:

* `time_periods`: display-ready weekday labels and time-range strings.
* `time_periods_structured`: structured values intended for app logic and custom rendering.

The keys in `time_periods_structured` use ISO weekday numbering:

* `1` = Monday
* `2` = Tuesday
* `3` = Wednesday
* `4` = Thursday
* `5` = Friday
* `6` = Saturday
* `7` = Sunday

Each weekday contains one or more time ranges with `start_time` and `end_time` values in `HH:MM:SS` format.

```json
{
  "time_periods_structured": {
    "4": [
      {
        "start_time": "15:00:00",
        "end_time": "16:00:00"
      }
    ]
  }
}
```

Use the structured field when your app needs predictable weekday and time values rather than localized display strings.

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


---

# 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/earning-rules-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.
