# Percent Value Distribution

{% hint style="danger" %}
Please note this is an advanced use case. Contact Open Loyalty Support team if in doubt.

**Make sure to test any configuration thoroughly.**
{% endhint %}

The **Percent Value Distribution** function is a powerful tool used in campaign effects to calculate rewards based on **tiered value thresholds**. It enables you to dynamically apply different reward percentages depending on how much value a member has accumulated over time—commonly used for cashback-style or volume-based reward campaigns.

This function works in combination with **Achievements**, which allow you to track ongoing member progress (e.g., monthly spend), and issue campaign rewards based on the configured percentage ranges.

***

### ⚙️ How the Function Works

```plaintext
percent_value_distribution(
  event.body.progressChanges[0], 
  [thresholds], 
  [percentValues], 
  event.body.progressStatuses[0].currentPeriodValue - event.body.progressChanges[0]
)
```

#### Breakdown of Parameters:

| Parameter                                                                           | Description                                                       |
| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `event.body.progressChanges[0]`                                                     | Value of the current achievement progress (incremental progress). |
| `[thresholds]`                                                                      | An array defining cumulative value ranges.                        |
| `[percentValues]`                                                                   | An array of percentage values (as decimals) to apply per range.   |
| `event.body.progressStatuses[0].currentPeriodValue - event.body.progressChanges[0]` | Total accumulated value **before** the current progress.          |

***

### 💡 Example Use Case: Tiered Cashback

You want to give members cashback based on their monthly spending:

* **0–5,000** → 1%
* **5,000–7,500** → 1.2%
* **7,500–10,000** → 1.5%
* **10,000+** → 0%

To achieve this, use the following expression in your campaign effect:

```plaintext
percent_value_distribution(
  event.body.progressChanges[0], 
  [5000, 7500, 10000], 
  [0.01, 0.012, 0.015, 0], 
  event.body.progressStatuses[0].currentPeriodValue - event.body.progressChanges[0]
)
```

***

### 🧱 Step-by-Step Setup

#### 1️⃣ Create an Achievement

This tracks total member spend over a defined period.

* **Type**: Direct → Transaction
* **Occurrence**: Consecutive month
* **Goal**: Set a high goal (e.g., 10,000,000) to allow continuous tracking
* **Achievement counting**: Sum of event attributes

This ensures member progress is calculated on **monthly spend** using transaction value.

***

#### 2️⃣ Create a Campaign

This campaign will apply the tiered reward logic using the data from the Achievement.

* **Trigger**: Internal event → `Achievement progressed`
* **Condition**: **Achievement is one of -** select the achievemnt
* **Effect**: Add Units\
  Formula:

  ```plaintext
  percent_value_distribution(
    event.body.progressChanges[0], 
    [5000, 7500, 10000], 
    [0.01, 0.012, 0.015, 0], 
    event.body.progressStatuses[0].currentPeriodValue - event.body.progressChanges[0]
  )
  ```

***

#### 3️⃣ How It Works in Practice

Each time a member makes a transaction:

* The **Achievement** updates their total monthly spend.
* If the progress event is triggered, the **Campaign** evaluates the correct percentage range.
* Units are issued based on that portion of value:

  Example: If a member spends $10,000 in one month:

  * First $5,000 → 1% = **50 units**
  * Next $2,500 → 1.2% = **30 units**
  * Next $2,500 → 1.5% = **37.5 units**
  * Above $10,000 → 0% = **0 units**

  ✅ **Total reward: 117.5 units**

***

### 📝 Summary

**Percent Value Distribution** allows you to dynamically scale rewards based on accumulated value thresholds. Combined with Achievements, it supports advanced use cases like tiered cashback or progressive bonuses—unlocking highly personalized loyalty experiences.


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.openloyalty.io/main-features/campaigns/campaigns-and-referral-campaigns/creating-campaigns/percent-value-distribution.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.