> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Referrals

> Reward customers who invite others with a referral code, and optionally reward the invited customers too.

Referral campaigns let customers invite others using a unique referral code. When someone completes a qualifying action that includes that code, Masivo can reward the **referrer** (who shared the code) and, if configured, the **referee** (who used it).

## How referrals work

```mermaid theme={null}
flowchart LR
  A[Referrer requests code] --> B[Referee emits event\n+ referral_code]
  B --> C{Code valid?}
  C -- No --> Skip[No referral rewards]
  C -- Yes --> D[Optional referee rewards]
  C -- Yes --> E[Create REWARD_REFERRER\nevent for referrer]
  E --> F[Referrer rules applied]
```

### Roles

| Role     | Who                                                          | What happens                                                                   |
| -------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------ |
| Referrer | Owner of the referral code                                   | Receives rewards from campaign `rules` via a generated `REWARD_REFERRER` event |
| Referee  | Customer who sends the qualifying event with `referral_code` | May receive rewards from `attributes.referee_rules` on the same event          |
| Code     | Row in `referral_codes`                                      | Ties a customer + campaign to a shareable `code`, with use limits              |

Self-referral is ignored: the same customer cannot use their own code, and `referred_customer_id` matching the event customer is rejected.

## Requesting a code

Referrers obtain a code through the Storefront API:

`POST /api/storefront/v1/customers/{id}/referrals/request-code`

| Body field    | Description                   |
| ------------- | ----------------------------- |
| `campaign_id` | Referral campaign UUID        |
| `brand_id`    | Brand external id (or `null`) |

If the customer already has a code for that campaign, the existing row is returned. New codes:

* Are 8 characters from `A–Z` / `0–9` (ambiguous characters like `I` and `O` are omitted)
* Set `max_uses` from `attributes.max_participations_per_customer`
* Start with `uses_count: 0`

## Qualifying event

The referee must emit a [behavior event](/api-reference/behavior/events/post) that:

1. Matches campaign `attributes.trigger` (for example `"PURCHASE"` or a custom type such as `"REFERRALS"`)
2. Includes a valid `referral_code`
3. Is processed as fulfilled when you want rewards applied (same fulfillment rules as other campaigns)

On a successful match, Masivo:

1. Increments the code's `uses_count` (blocked when `uses_count >= max_uses`)
2. Increments campaign `attributes.uses`
3. Applies **referee** rewards from `attributes.referee_rules` on the referee's event (if any rules exist)
4. Inserts a `REWARD_REFERRER` event for the referrer and processes it asynchronously with the campaign's main `rules`

### Referrer vs referee rules

| Rules            | Stored as                  | Applied to                                   |
| ---------------- | -------------------------- | -------------------------------------------- |
| Referrer rewards | Campaign `rules`           | Referrer's generated `REWARD_REFERRER` event |
| Referee rewards  | `attributes.referee_rules` | Referee's original event                     |

At least one of referrer or referee rewards must be configured when creating the campaign. Referrer rules can include normal conditions (payment method, audiences, and so on). Those conditions are evaluated on the `REWARD_REFERRER` event context.

Example shape:

```json theme={null}
{
  "rules": [
    {
      "conditions": [],
      "effects": [{ "type": "POINTS", "amount": 100 }]
    }
  ],
  "attributes": {
    "trigger": "PURCHASE",
    "privacy": "PUBLIC",
    "max_participations_per_customer": 5,
    "stock": 5000,
    "uses": 0,
    "referee_rules": [
      {
        "conditions": [],
        "effects": [{ "type": "POINTS", "amount": 50 }]
      }
    ]
  }
}
```

## Campaign configuration

| Field                             | Type                    | Description                                                  |
| --------------------------------- | ----------------------- | ------------------------------------------------------------ |
| `trigger`                         | `string`                | Event type that must match the referee's event               |
| `privacy`                         | `"PRIVATE" \| "PUBLIC"` | Controls visibility in public-facing APIs                    |
| `max_participations_per_customer` | `number` (1–100)        | Copied to each code as `max_uses`                            |
| `stock`                           | `number`                | Campaign attribute stored for configuration / analytics      |
| `uses`                            | `number`                | Campaign-level counter; incremented when a referral succeeds |
| `referee_rules`                   | `Rule[]` (optional)     | Rewards for the customer who used the code                   |

Hard limit enforced at processing time is the **code** use limit (`uses_count` vs `max_uses`), not `stock`.

## Event reversal

Reversing the referee's original event can also reverse the linked referrer reward:

1. Masivo looks up a `REWARD_REFERRER` event whose `data.original_event_id` matches the reversed event.
2. If that referrer event is `RESOLVED`, it is included in the normal reversal flow.

There is no separate public “referral history” endpoint; progress is visible via wallet lines, transactions, and events.

## Comparison with Punch Cards

|                       | Referrals                          | Punch Cards                            |
| --------------------- | ---------------------------------- | -------------------------------------- |
| Trigger               | Referee event with `referral_code` | Qualifying event for the same customer |
| Progress              | Code uses + invite rewards         | Punches on a card                      |
| Parties rewarded      | Referrer and/or referee            | Only the event customer                |
| Extra Storefront step | Request code                       | List punch cards                       |
| Time pressure         | Use limits on codes                | Card finishes at max punches           |