# Referral events

Source: https://gokarla.io/docs/platform/events/referrals

# Referral events

Referral events are addressed to the **advocate**: the customer whose referral
code a friend used. They use the hierarchy and envelope documented in the
[Events overview](/docs/platform/events/overview).

**Ref pattern**: `referrals/{action}`

## Catalog

| Event group               | Ref                        | Description                                               |
| ------------------------- | -------------------------- | --------------------------------------------------------- |
| `referral_friend_ordered` | `referrals/friend_ordered` | A friend placed an order with the advocate's code         |
| `referral_reward_earned`  | `referrals/reward_earned`  | The advocate's reward code was issued after the delay ran |

Webhooks subscribed to `*` or `referrals` receive both events. Subscribe to a
single ref to receive only that event.

## Context

`context.order` is the advocate's order (the one their referral code came
from) and `context.customer` is the advocate. No event is sent when the
advocate's order has no customer id (e.g. guest checkout) or no address.

## `event_data` shape

Every key is always present; values marked nullable can be `null`.

### `referral_friend_ordered`

| Field                    | Type             | Description                                                                                        |
| ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------- |
| `referral_code`          | string           | The advocate's referral code                                                                       |
| `share_url`              | string, nullable | Link that applies the code in your store; `null` without a storefront URL or once the code expired |
| `reward_value`           | number           | Advocate reward amount or percentage                                                               |
| `reward_type`            | string           | `percentage` or `fixed`                                                                            |
| `currency`               | string, nullable | Currency of a fixed reward                                                                         |
| `reward_delay_days`      | number           | Days after the friend's order until the reward is issued                                           |
| `friend_order_number`    | string, nullable | The friend's order number                                                                          |
| `unique_id`              | string           | Idempotency key, unique per referral                                                               |
| `referral_redemption_id` | string           | Karla's id for this referral                                                                       |
| `event_group`            | string           | `referral_friend_ordered`                                                                          |

```jsx title="referral_friend_ordered event_data"
{
  "referral_code": "ANNA-7KQ2",
  "share_url": "https://shop.example.com/discount/ANNA-7KQ2?redirect=/",
  "reward_value": 10.0,
  "reward_type": "percentage",
  "currency": "EUR",
  "reward_delay_days": 14,
  "friend_order_number": "1042",
  "unique_id": "karla_referral_friend_ordered:5b1f0c9e-2a8d-4f6b-9c1e-3d7a2b4e6f80",
  "referral_redemption_id": "5b1f0c9e-2a8d-4f6b-9c1e-3d7a2b4e6f80",
  "event_group": "referral_friend_ordered"
}
```

### `referral_reward_earned`

| Field                    | Type             | Description                                  |
| ------------------------ | ---------------- | -------------------------------------------- |
| `reward_code`            | string           | The discount code issued to the advocate     |
| `reward_value`           | number           | Reward amount or percentage                  |
| `reward_type`            | string           | `percentage` or `fixed`                      |
| `currency`               | string, nullable | Currency of a fixed reward                   |
| `reward_expires_at`      | string           | When the reward code expires (ISO 8601, UTC) |
| `friend_order_number`    | string, nullable | The friend's order number                    |
| `unique_id`              | string           | Idempotency key, unique per referral         |
| `referral_redemption_id` | string           | Karla's id for this referral                 |
| `event_group`            | string           | `referral_reward_earned`                     |

```jsx title="referral_reward_earned event_data"
{
  "reward_code": "REWARD-9XP4",
  "reward_value": 10.0,
  "reward_type": "fixed",
  "currency": "EUR",
  "reward_expires_at": "2027-01-15T00:00:00+00:00",
  "friend_order_number": "1042",
  "unique_id": "karla_referral_reward_earned:5b1f0c9e-2a8d-4f6b-9c1e-3d7a2b4e6f80",
  "referral_redemption_id": "5b1f0c9e-2a8d-4f6b-9c1e-3d7a2b4e6f80",
  "event_group": "referral_reward_earned"
}
```

## Delivery

Referral events are sent once, best effort: a delivery that fails is not
retried. Don't rely on them as guaranteed delivery; the reward code is also
issued in Shopify regardless of whether the event arrives.

In the Karla Shopify app, both events are available as Shopify Flow triggers,
**Referral Friend Ordered** and **Referral Reward Earned**. Their `karla`
object carries `referralCode`, `shareUrl`, `rewardCode`, `rewardValue`,
`rewardType`, `currency`, `rewardDelayDays`, `rewardExpiresAt` and
`friendOrderNumber` (for example `{{karla.rewardCode}}`); fields the event does
not carry are empty. `unique_id`, `referral_redemption_id` and `event_group` are
webhook-only and not available in Flow.

## Related

- [Events overview](/docs/platform/events/overview) — hierarchy,
  envelope, and filtering syntax.
- [Webhooks](/docs/guides/notify/webhooks) — subscribing to events over HTTP.