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.
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 or raised after the delay ran |
referral_code_expiring | referrals/code_expiring | The advocate's referral code expires within the next 7 days |
Webhooks subscribed to * or referrals receive all referral 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.
referral_friend_ordered is not sent when:
- the friend had ordered from your store before (the friend keeps the discount, but the advocate earns no reward for a returning customer)
- the friend is the advocate (same customer id or email)
- the code had expired when the friend ordered
- the advocate's order had not reached Karla yet when the friend ordered
referral_reward_earned is sent once the reward delay has passed after the
friend's order was delivered: the delay starts when Shopify reports the order
fully fulfilled and the last outbound parcel of the order is delivered. A
parcel delivered later moves the reward later. When Karla never learns of the
delivery (for example no tracking or an unsupported carrier), the reward is
due the reward delay plus 10 days after the order was fulfilled. It is not
sent when the friend's order was refunded, voided or deleted, or when the
friend turns out to be the advocate.
referral_code_expiring is sent once per referral code, by a nightly run,
when a live code expires within the next 7 days. It is not sent when the shop
has referrals switched off.
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 | Shop currency for a fixed reward; the advocate order's currency for a percentage reward |
reward_delay_days | number | Days after the friend's order is delivered 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 |
{
"referral_code": "ANN-7KQ",
"share_url": "https://shop.example.com/discount/ANN-7KQ?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 | Current value of the reward code. A further referral raises the advocate's open code instead of issuing a new one, so this is the running total, not the amount of this referral |
reward_type | string | percentage or fixed |
currency | string, nullable | Shop currency for a fixed reward; the advocate order's currency for a percentage reward |
reward_expires_at | string | When the reward code expires (ISO 8601, UTC); renewed when the code is raised |
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 |
{
"reward_code": "REF-A1B2C3D4",
"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"
}
referral_code_expiring#
| Field | Type | Description |
|---|---|---|
referral_code | string | The advocate's referral code that is about to expire |
share_url | string, nullable | Link that applies the code in your store; null without a storefront URL or once the code expired |
expires_at | string | When the code expires (ISO 8601, UTC) |
redemption_count | number | How many friend orders used the code so far |
friend_reward_value | number | The friend's discount amount or percentage |
friend_reward_type | string | percentage or fixed |
currency | string, nullable | Shop currency for a fixed discount; the advocate order's currency for a percentage discount |
unique_id | string | Idempotency key, unique per referral code |
referral_code_id | string | Karla's id for this referral code |
event_group | string | referral_code_expiring |
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, referral_friend_ordered and referral_reward_earned
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.
referral_code_expiring has no Flow trigger; use a webhook or the
karla_referral_code_expiring Klaviyo metric for it.
Related#
- Events overview — hierarchy, envelope, and filtering syntax.
- Webhooks — subscribing to events over HTTP.