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