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 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 |
{
"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 |
{
"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 — hierarchy, envelope, and filtering syntax.
- Webhooks — subscribing to events over HTTP.