> For the complete documentation index, see [llms.txt](https://help.dollarlabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.dollarlabs.io/dollarback-store-credit/referral-engine.md).

# Referral Engine

This article walks you through the new **Referral Engine**, which now supports **multiple referral configurations running in parallel**.

{% embed url="<https://dollarlabs.neetorecord.com/watch/5aa7d3529becc7a45265>" %}

***

### What’s New?

You’re no longer limited to a single referral setup.

With the new Referral Engine, you can:

* Create **multiple referral configurations**
* Keep **all configurations active at the same time**
* Target different customer segments (e.g. VIP vs All Customers)
* Control priority when multiple configs apply to the same customer

<figure><img src="/files/IcZR6ZjLHeUg3x20EZiw" alt=""><figcaption></figcaption></figure>

***

### Getting Started

#### Existing Users (Upgrading from the Old Engine)

If you’re coming from the older version:

* You’ll see **one disabled configuration**
* A message will prompt you to upgrade

**To upgrade:**

1. Add an **Internal Title**
2. Set a **Code Prefix**
3. Enable the configuration
4. Click **Save**

That’s it—your referral engine is upgraded.

***

#### New Users (Fresh Install)

If you’ve just installed the app:

* You’ll start with **no configurations**
* Click **Add Config** to create your first referral setup

***

### Creating a Referral Configuration

Each referral configuration has the following sections:

***

#### 1. Internal Title

A name used internally to identify the configuration.\
This does **not** affect customers.

***

#### 2. Code Prefix (Required)

This defines the **prefix used in referral codes**.

Examples:

* `ALL-`
* `VIP-`

⚠️ **Important:**\
Once saved, the **code prefix cannot be changed** for that configuration.

{% hint style="info" %}
You can have a only one config that doesn't have any prefix.
{% endhint %}

***

#### 3. Customer Tags (Optional)

Use this to restrict a configuration to specific customers.

Example:

* Apply only to customers tagged `VIP`
* Leave empty to apply to **all customers**

***

#### 4. Referrer Reward (Who Shares the Code)

This is the reward earned by the customer who refers someone.

Options:

* **Percentage of order**
* **Fixed amount**

Notes:

* Percentage rewards follow your **global cashback settings**
* Reward issuance timing depends on your cashback rules (order created / paid / fulfilled)

***

#### 5. Referee Discount (Who Uses the Code)

This is the incentive for the referred customer placing an order.

Options:

* **Percentage discount**
* **Fixed discount amount**

This discount is applied when the referral code is used at checkout.

***

#### 6. Minimum Order Value

Set a minimum order total required to use the referral code.

If the order value doesn’t meet this amount:

* The discount **cannot be applied**

***

#### 7. Usage Limits

Control how referral codes can be used.

**a. New Customers Only**

* Checks if the customer has **any previous orders**
* If enabled, only brand-new customers can apply the code

⚠️ Use this setting carefully—it’s strict and irreversible per order.

**b. Usage Per Referred Customer**

* Defines how many times a referred customer can use the code
* Default is **1**

Once used, the code can’t be reused by that customer.

***

#### 8. Referrer Reward Expiry

Set how long the referrer’s reward remains valid.

* Expiry starts from the **date the reward is issued**
* Issuance timing depends on order status rules (created / paid / fulfilled)

***

#### 9. Refunds & Order Changes (Advanced Plan)

If you’re on the **Advanced ($39) plan**:

* Referral rewards automatically adjust if:
  * Orders are refunded
  * Orders are cancelled
  * Order values change

This keeps rewards accurate and abuse-free.

***

#### 10. Combination Rules

Define which **other discounts** the referral code can stack with.

You control:

* Which discounts are allowed
* Which discounts are blocked

***

### How Multiple Configs Work Together

#### Priority & Conflicts

If a customer qualifies for **multiple referral configurations**:

* The system applies the **topmost config**
* You can **reorder configs** to control priority

***

#### Example Scenario

You have two configs:

1. **VIP Customers**
2. **All Customers**

If a customer:

* Has the `VIP` tag → VIP config is applied
* Doesn’t have the tag → All Customers config is applied
* Has both → The **higher-priority config** wins

When customer tags change, the referral code updates automatically.

***

### Summary

With the new Referral Engine, you can:

* Run multiple referral programs simultaneously
* Target different customer segments
* Control priority and stacking behavior
* Automatically handle refunds and order edits (Advanced plan)

***

### Need Help?

If you have questions or need help setting up advanced referral programs:

* Reach out via in-app chat
* Or email us at **<support@dollarlabs.io>**

We’re happy to help 🚀