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


---

# 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.dollarlabs.io/dollarback-store-credit/referral-engine.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.