Docs/Events/Referral events

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 groupRefDescription
referral_friend_orderedreferrals/friend_orderedA friend placed an order with the advocate's code
referral_reward_earnedreferrals/reward_earnedThe advocate's reward code was issued or raised after the delay ran
referral_code_expiringreferrals/code_expiringThe 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#

FieldTypeDescription
referral_codestringThe advocate's referral code
share_urlstring, nullableLink that applies the code in your store; null without a storefront URL or once the code expired
reward_valuenumberAdvocate reward amount or percentage
reward_typestringpercentage or fixed
currencystring, nullableShop currency for a fixed reward; the advocate order's currency for a percentage reward
reward_delay_daysnumberDays after the friend's order is delivered until the reward is issued
friend_order_numberstring, nullableThe friend's order number
unique_idstringIdempotency key, unique per referral
referral_redemption_idstringKarla's id for this referral
event_groupstringreferral_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#

FieldTypeDescription
reward_codestringThe discount code issued to the advocate
reward_valuenumberCurrent 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_typestringpercentage or fixed
currencystring, nullableShop currency for a fixed reward; the advocate order's currency for a percentage reward
reward_expires_atstringWhen the reward code expires (ISO 8601, UTC); renewed when the code is raised
friend_order_numberstring, nullableThe friend's order number
unique_idstringIdempotency key, unique per referral
referral_redemption_idstringKarla's id for this referral
event_groupstringreferral_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#

FieldTypeDescription
referral_codestringThe advocate's referral code that is about to expire
share_urlstring, nullableLink that applies the code in your store; null without a storefront URL or once the code expired
expires_atstringWhen the code expires (ISO 8601, UTC)
redemption_countnumberHow many friend orders used the code so far
friend_reward_valuenumberThe friend's discount amount or percentage
friend_reward_typestringpercentage or fixed
currencystring, nullableShop currency for a fixed discount; the advocate order's currency for a percentage discount
unique_idstringIdempotency key, unique per referral code
referral_code_idstringKarla's id for this referral code
event_groupstringreferral_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.

Was this helpful?