> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/referrals.md).

# Referrals

Running a refer-a-friend programme: sharing referral links, passing the referrer's token at registration, and rewarding both sides when the friend qualifies.

In a referral programme, a member invites a friend; when the friend joins and does something that qualifies — usually a first purchase — Open Loyalty rewards the referrer, the friend, or both. Open Loyalty keeps the referral relationship and runs the rules; your channels build the links and pass the token back at registration.

For the Admin Panel side, see [Referral campaigns](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/referral-campaign), [Referred members](https://help.openloyalty.io/members-and-activity/members/referred-members) and the [Referral programs FAQ](https://help.openloyalty.io/faq/referral-programs).

## Who does what

| Area                           | Responsibility                                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| **Admin Panel**                | Referral campaigns: trigger on the friend's activity, rules for referrer and referee, referral depth, limits                   |
| **Integration layer**          | Builds referral links from the member's token, carries the token through registration, sends the friend's qualifying activity  |
| **Website / app**              | "Invite a friend" with share options; captures the token from the link (URL parameter, deep link) and keeps it through sign-up |
| **CRM / marketing automation** | Tells both sides when a reward is given                                                                                        |

## Design decisions

| Decision                  | Options                                                       | Recommendation                                                                                                                           |
| ------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| What qualifies a referral | Registration, first purchase, a minimum spend, a custom event | A first purchase (or an event that costs the friend something). Rewarding registration alone invites fake sign-ups.                      |
| Who is rewarded           | Referrer, referee, or both                                    | Both, with separate rules for referrer and referee in the same campaign.                                                                 |
| Referral depth            | Direct referrer only, or several levels                       | Direct only unless multi-level rewards are part of the proposition; set **Referral max levels** in the campaign's referral reward depth. |
| Limits                    | Unlimited, or a cap per referrer and period                   | Cap rewarded referrals per referrer (e.g. 5 a year) to limit abuse.                                                                      |
| Link format               | Your own domain, app deep link                                | Your own URL with the token as a parameter (e.g. `https://example.com/join?ref={token}`); Open Loyalty doesn't generate links.           |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create a referral campaign triggered by the friend's qualifying activity, with rules for the referrer and the referee, the referral depth and limits.
{% endstep %}

{% step %}

### Build the member's link

Read the member with `GET /api/{storeCode}/member/{member}` — their own token is in **`referralToken`** — and build the share link with it.
{% endstep %}

{% step %}

### Pass the token at registration

Capture the token from the link and keep it through the whole sign-up (including email verification or app install). Send it as **`customer.referrerToken`** in `POST /api/{storeCode}/member`. This links the friend to the referrer at creation.
{% endstep %}

{% step %}

### Send the qualifying activity

The friend's purchase or event goes through the normal [transaction](https://help.openloyalty.io/implementation-guide/module-checklists/transactions.md) or [custom event](https://help.openloyalty.io/implementation-guide/module-checklists/custom-events.md) flow. The referral campaign rewards each side.
{% endstep %}

{% step %}

### Tell both sides

Use `CampaignEffectWasApplied` to message the referrer and the friend.
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-19fe4fe953bbf6036b9c13eff32bc81ba6bb8bab%2Fig-referrals-flow.png?alt=media" alt="Share: the referrer asks for a referral link; the integration layer reads the member and gets their referralToken, and returns a link with the token as a parameter, which the referrer shares. Join: the friend opens the link and registers; the integration layer creates the member with customer.referrerToken set to the token, and Open Loyalty links the new member to the referrer. Qualify: the friend&#x27;s first purchase or event is sent; the referral campaign runs its rules for referee and referrer with limits, and CampaignEffectWasApplied webhooks let the channel tell the referrer they earned points." width="728"><figcaption><p>Share, join and qualify</p></figcaption></figure>

{% hint style="warning" %}
The token has to be sent **when the friend's member is created**. A referrer can be added afterwards (`POST /member/{member}/referral`), but referral campaigns don't run retrospectively for activity that already happened.
{% endhint %}

## Go-live checklist

### Admin Panel

* [ ] The referral campaign triggers on the agreed qualifying activity, with rules for referrer and referee.
* [ ] Referral depth and per-referrer limits are set.

### Integration layer

* [ ] Share links are built from `referralToken`.
* [ ] Registration sends `customer.referrerToken` whenever the customer arrived through a link.

### Website / app

* [ ] The token survives the whole sign-up: redirects, email verification, app install.
* [ ] "Invite a friend" is available to every member, including those who were referred themselves.

### Validation

* [ ] A friend who registers through a link appears under the referrer's referrals.
* [ ] The friend's first qualifying purchase rewards both sides once.
* [ ] A second qualifying purchase doesn't reward the referrer again (if the campaign says so).
* [ ] Registration without a token creates a member with no referrer.

## Key endpoints

* `GET /api/{storeCode}/member/{member}` — [Get member's details](https://help.openloyalty.io/api-reference/member/get-members-details) (`referralToken`)
* `POST /api/{storeCode}/member` — [Add a member](https://help.openloyalty.io/api-reference/member/add-a-member) (`customer.referrerToken`)
* `POST /api/{storeCode}/member/{member}/referral` — [Create member's referral](https://help.openloyalty.io/api-reference/member/create-members-referral)
* `GET /api/{storeCode}/referral` — [Get referrals list](https://help.openloyalty.io/api-reference/member/get-referrals-list)

**Webhooks:** [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied)

{% hint style="warning" %}
**Common pitfalls**

* Mixing up the two names: the member's own token is `referralToken`; the token sent at registration is `referrerToken`.
* Losing the token during sign-up (a redirect or app store install drops the URL parameter).
* Rewarding registration alone: easy to farm with throwaway accounts.
* Adding the referrer after the friend's first purchase and expecting the reward to follow.
  {% endhint %}


---

# 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://help.openloyalty.io/implementation-guide/module-checklists/referrals.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.
