Referrals
event_referral_success
This event will occur when the referred friend clicks on the referral link and makes his first purchase.
Note: The order_info field will be null for all activities other than purchase activities.
If a guest makes a purchase and is not enrolled in the loyalty program, the friend info in payload will appear as follows:
"friend_info": {
"email_address": "annascott286@gmail.com",
"member_id": "anna.scott286"
}Request
We send events to your webhook's URL with POST and a JSON body. Events are batched: a request can carry several events of this type. See Receiving Webhooks for batch sizes and retries, and Webhook Event Signatures to verify the request.
Headers
| Header | Description |
|---|---|
x-zinrelo-signature | The HMAC-SHA512 hex digest of <request body>:<nonce>, computed with the webhook's secret key. See Webhook Event Signatures. |
nonce | The Unix time, in milliseconds, at which the request was signed. It's part of the signed message. |
Payload
| Field | Type | Description |
|---|---|---|
request_id | string | A unique identifier of this webhook request. |
total_count | integer | The number of events in the batch (events). |
created_date | string | When the webhook request was created, as MM/DD/YYYY HH:MM:SS. |
events | array of object | The events in this batch. |
events[].id | string | The unique identifier of the event. Use it to detect events you already processed. |
events[].event_type | string | The type of event. One of event_referral_success. |
events[].data | object | The event's data. |
events[].data.friend_info (optional) | object | The friend_info object of the event's data. Which fields are present depends on the event. |
events[].data.friend_info.email_address (optional) | string | The email address of the member. |
events[].data.friend_info.id (optional) | string | The internal ID generated by TrueLoyal. |
events[].data.friend_info.first_name (optional) | string | The first name of the member. |
events[].data.friend_info.last_name (optional) | string | The last name of the member. |
events[].data.friend_info.address (optional) | object | |
events[].data.friend_info.address.city (optional) | string | Member's city. |
events[].data.friend_info.address.country (optional) | string | Member's country. |
events[].data.friend_info.address.line2 (optional) | string | The member address. |
events[].data.friend_info.address.line1 (optional) | string | The member address. |
events[].data.friend_info.address.state (optional) | string | Member's state. |
events[].data.friend_info.address.postal_code (optional) | string | Member's postal code. |
events[].data.friend_info.phone_number (optional) | string | The phone number of the member. |
events[].data.friend_info.member_id (optional) | string | The unique identifier of the member defined by an Admin. |
events[].data.friend_info.member_status (optional) | string | The current status of the member- ‘active’ , ‘blocked’, ‘opted_out’. ‘active’ member is the one accumulating loyalty points and has access to rewards and earning opportunities. ‘blocked’ member is prohibited from participating in the program. ‘opted_out’ member is the one who has chosen to opt out of the loyalty program. |
events[].data.friend_info.member_tags (optional) | array of string | The tags assocaited with a member. |
events[].data.friend_info.number_of_purchases (optional) | integer | The number of purchases made by a member. |
events[].data.friend_info.number_of_redemptions (optional) | integer | The number of redemptions made by a member. |
events[].data.friend_info.birthdate (optional) | string | Birthdate of the loyalty member. Expected date format: MM/DD/YYYY or MM/DD Irrespective of the year passed, 1904 will be set as a default value. |
events[].data.friend_info.enrollment_date (optional) | string | The date on which the member joined the loyalty program. |
events[].data.friend_info.last_modified_date (optional) | string | The most recent date on which a member's profile was updated. |
events[].data.friend_info.first_purchase_date (optional) | string | The first purchase date of the member. |
events[].data.friend_info.instagram_handle (optional) | string | The instagram handle of the member. |
events[].data.friend_info.last_purchase_date (optional) | string | The last purchase made by a member. |
events[].data.friend_info.anniversary_date (optional) | string | The anniversary date of the member. Expected date format: MM/DD/YYYY or MM/DD In case, where a year has not been passed the default year will be set as 1904. |
events[].data.friend_info.twitter_handle (optional) | string | The twitter handle of the member. |
events[].data.friend_info.preferred_language (optional) | string | The preferred language of the member. |
events[].data.friend_info.tier_info (optional) | object | |
events[].data.friend_info.tier_info.tier_qualification_units (optional) | integer | |
events[].data.friend_info.tier_info.current_period_start (optional) | string | The start date of the current tier cycle. |
events[].data.friend_info.tier_info.loyalty_tier_name (optional) | string | The name of the current tier. |
events[].data.friend_info.tier_info.qualified_points (optional) | integer | The qualified points for tier calculation. |
events[].data.friend_info.tier_info.loyalty_tier_id (optional) | string | The unique tier ID stored in TrueLoyal. |
events[].data.friend_info.tier_info.current_period_end (optional) | string | The end date of current tier cycle. |
events[].data.friend_info.lifetime_points_earned (optional) | integer | The total points earned in a member's account since he joined the program. |
events[].data.friend_info.lifetime_points_expired (optional) | integer | The total points expired from a member's account since he joined the program. |
events[].data.friend_info.available_points (optional) | integer | The avaliable points of the member. |
events[].data.friend_info.points_onhold (optional) | integer | |
events[].data.friend_info.lifetime_points_deducted (optional) | integer | The total points deducted from a member's account since he joined the program. |
events[].data.friend_info.lifetime_points_redeemed (optional) | integer | The total points redeemed from a member's account since he joined the program. |
events[].data.friend_info.referral_URL (optional) | string | The unique referral url of the member. |
events[].data.friend_info.custom_attributes (optional) | object | |
events[].data.friend_info.custom_attributes.Gender (optional) | array of string | |
events[].data.friend_info.custom_attributes.Number of purchases (optional) | integer | |
events[].data.friend_info.custom_attributes.List of favourite place (optional) | array of string | |
events[].data.friend_info.custom_attributes.Review date (optional) | string | |
events[].data.friend_info.custom_attributes.City_Name (optional) | string | |
events[].data.friend_info.custom_attributes.Marital_Status (optional) | string | |
events[].data.friend_info.custom_attributes.Income_Source (optional) | string | |
events[].data.friend_info.custom_attributes.Age_In_Years (optional) | string | |
events[].data.friend_info.custom_attributes.Gender_Identity (optional) | string | |
events[].data.friend_info.custom_attributes.Graduation_Date (optional) | string | |
events[].data.friend_info.revenue (optional) | integer | |
events[].data.friend_info.aov (optional) | number | |
events[].data.friend_info.deleted_date (optional) | null | |
events[].data.friend_info.referral_code (optional) | string | The unique referral code of the member. |
events[].data.referrer_info (optional) | object | The referrer_info object of the event's data. Which fields are present depends on the event. |
events[].data.referrer_info.id (optional) | string | The internal ID generated by TrueLoyal. |
events[].data.referrer_info.first_name (optional) | string | The first name of the member. |
events[].data.referrer_info.last_name (optional) | string | The last name of the member. |
events[].data.referrer_info.email_address (optional) | string | The email address of the member. |
events[].data.referrer_info.address (optional) | object | |
events[].data.referrer_info.address.city (optional) | string | Member's city. |
events[].data.referrer_info.address.country (optional) | string | Member's country. |
events[].data.referrer_info.address.line2 (optional) | string | The member address. |
events[].data.referrer_info.address.line1 (optional) | string | The member address. |
events[].data.referrer_info.address.state (optional) | string | Member's state. |
events[].data.referrer_info.address.postal_code (optional) | string | Member's postal code. |
events[].data.referrer_info.phone_number (optional) | string | The phone number of the member. |
events[].data.referrer_info.member_id (optional) | string | The unique identifier of the member defined by an Admin. |
events[].data.referrer_info.member_status (optional) | string | The current status of the member- ‘active’ , ‘blocked’, ‘opted_out’. ‘active’ member is the one accumulating loyalty points and has access to rewards and earning opportunities. ‘blocked’ member is prohibited from participating in the program. ‘opted_out’ member is the one who has chosen to opt out of the loyalty program. |
events[].data.referrer_info.member_tags (optional) | array of string | The tags assocaited with a member. |
events[].data.referrer_info.number_of_purchases (optional) | integer | The number of purchases made by a member. |
events[].data.referrer_info.number_of_redemptions (optional) | integer | The number of redemptions made by a member. |
events[].data.referrer_info.birthdate (optional) | string | Birthdate of the loyalty member. Expected date format: MM/DD/YYYY or MM/DD Irrespective of the year passed, 1904 will be set as a default value. |
events[].data.referrer_info.enrollment_date (optional) | string | The date on which the member joined the loyalty program. |
events[].data.referrer_info.last_modified_date (optional) | string | The most recent date on which a member's profile was updated. |
events[].data.referrer_info.first_purchase_date (optional) | string | The first purchase date of the member. |
events[].data.referrer_info.instagram_handle (optional) | string | The instagram handle of the member. |
events[].data.referrer_info.last_purchase_date (optional) | string | The last purchase made by a member. |
events[].data.referrer_info.anniversary_date (optional) | string | The anniversary date of the member. Expected date format: MM/DD/YYYY or MM/DD In case, where a year has not been passed the default year will be set as 1904. |
events[].data.referrer_info.twitter_handle (optional) | string | The twitter handle of the member. |
events[].data.referrer_info.preferred_language (optional) | string | The preferred language of the member. |
events[].data.referrer_info.tier_info (optional) | object | |
events[].data.referrer_info.tier_info.current_period_start (optional) | string | The start date of the current tier cycle. |
events[].data.referrer_info.tier_info.loyalty_tier_name (optional) | string | The name of the current tier. |
events[].data.referrer_info.tier_info.qualified_points (optional) | integer | The qualified points for tier calculation. |
events[].data.referrer_info.tier_info.loyalty_tier_id (optional) | string | The unique tier ID stored in TrueLoyal. |
events[].data.referrer_info.tier_info.current_period_end (optional) | string | The end date of current tier cycle. |
events[].data.referrer_info.referral_code (optional) | string | The unique referral code of the member. |
events[].data.referrer_info.lifetime_points_earned (optional) | integer | The total points earned in a member's account since he joined the program. |
events[].data.referrer_info.lifetime_points_expired (optional) | integer | The total points expired from a member's account since he joined the program. |
events[].data.referrer_info.available_points (optional) | integer | The avaliable points of the member. |
events[].data.referrer_info.points_onhold (optional) | integer | |
events[].data.referrer_info.lifetime_points_deducted (optional) | integer | The total points deducted from a member's account since he joined the program. |
events[].data.referrer_info.lifetime_points_redeemed (optional) | integer | The total points redeemed from a member's account since he joined the program. |
events[].data.referrer_info.referral_URL (optional) | string | The unique referral url of the member. |
events[].data.referrer_info.custom_attributes (optional) | object | |
events[].data.referrer_info.custom_attributes.City_Name (optional) | string | |
events[].data.referrer_info.custom_attributes.Marital_Status (optional) | string | |
events[].data.referrer_info.custom_attributes.Income_Source (optional) | string | |
events[].data.referrer_info.custom_attributes.Age_In_Years (optional) | string | |
events[].data.referrer_info.custom_attributes.Gender_Identity (optional) | string | |
events[].data.referrer_info.custom_attributes.Graduation_Date (optional) | string | |
events[].data.referrer_info.revenue (optional) | integer | |
events[].data.referrer_info.aov (optional) | null | |
events[].data.referrer_info.deleted_date (optional) | null | |
events[].data.referral_success_activity_info (optional) | object | The referral_success_activity_info object of the event's data. Which fields are present depends on the event. |
events[].data.referral_success_activity_info.activity_id (optional) | string | The unique ID of the activity assigned by TrueLoyal. |
events[].data.referral_success_activity_info.activity_name (optional) | string | The activity name stored with TrueLoyal. |
events[].data.referral_success_activity_info.order_info (optional) | object | |
events[].data.referral_success_activity_info.order_info.order_total (optional) | string | |
events[].data.referral_success_activity_info.order_info.currency (optional) | string | |
events[].data.referral_success_activity_info.order_info.order_id (optional) | string | The unique ID associated with the placed order. This is system defined transaction attribute for "made_a_purchase" activity. |
events[].data.referral_success_activity_info.order_info.order_subtotal (optional) | string | |
events[].data.referral_success_activity_info.order_info.reason (optional) | string | The reason for making transaction. |
events[].data.referral_success_activity_info.order_info.device_type (optional) | string | |
events[].data.referral_success_activity_info.order_info.coupons (optional) | string | |
events[].data.referrer_reward_info (optional) | array of object | The referrer_reward_info object of the event's data. Which fields are present depends on the event. |
events[].data.referrer_reward_info[].id (optional) | string | |
events[].data.referrer_reward_info[].transaction_type (optional) | string | |
events[].data.referrer_reward_info[].member_id (optional) | string | |
events[].data.referrer_reward_info[].transaction_attributes (optional) | object | |
events[].data.referrer_reward_info[].transaction_attributes.reason (optional) | string | |
events[].data.referrer_reward_info[].transaction_attributes.tags (optional) | array | |
events[].data.referrer_reward_info[].approver_details (optional) | object | |
events[].data.referrer_reward_info[].approver_details.approver_id (optional) | null | |
events[].data.referrer_reward_info[].approver_details.approver_name (optional) | string | |
events[].data.referrer_reward_info[].approved_date (optional) | string | |
events[].data.referrer_reward_info[].last_modified_date (optional) | string | |
events[].data.referrer_reward_info[].created_date (optional) | string | |
events[].data.referrer_reward_info[].award_info (optional) | object | |
events[].data.referrer_reward_info[].award_info.activity_id (optional) | string | |
events[].data.referrer_reward_info[].award_info.activity_name (optional) | string | |
events[].data.referrer_reward_info[].award_info.points_status (optional) | string | |
events[].data.referrer_reward_info[].award_info.points (optional) | integer | |
events[].data.referrer_reward_info[].award_info.coupon_code (optional) | string | |
events[].data.referrer_reward_info[].points_expiration_date (optional) | string | |
events[].data.referrer_reward_info[].auto_approval_date (optional) | string |
Example
{
"request_id": "638718fdf9e076000ab268f6",
"total_count": 1,
"events": [
{
"id": "638718ff5efcad6bb4286b36",
"event_type": "event_referral_success",
"data": {
"friend_info": {
"id": "638718faf9e07600094f239c",
"first_name": "Anna",
"last_name": "Scott",
"email_address": "annascott286@gmail.com",
"address": {
"city": "Palo Alto",
"country": "US",
"line2": "530 Lytton Ave",
"line1": "Suite #200",
"state": "CA",
"postal_code": "94301"
},
"phone_number": "+1-6507017756",
"member_id": "anna.scott286",
"member_status": "active",
"member_tags": [
"referral",
"referredfriend"
],
"number_of_purchases": 1,
"number_of_redemptions": 0,
"birthdate": "10/31/1987 00:00:00",
"enrollment_date": "11/30/2022 00:00:00",
"last_modified_date": "11/30/2022 00:00:00",
"first_purchase_date": "11/30/2022 00:00:00",
"instagram_handle": "www.instagram.com/anna",
"last_purchase_date": "11/30/2022 00:00:00",
"anniversary_date": "10/29/2022 00:00:00",
"twitter_handle": "www.twitter.com/anna",
"preferred_language": "English",
"tier_info": {
"tier_qualification_units": 100,
"current_period_start": "03/01/2022 00:00:00",
"loyalty_tier_name": "Silver",
"qualified_points": 1190,
"loyalty_tier_id": "zrl_silver",
"current_period_end": "02/28/2023 23:59:59"
},
"referral_code": "TES855D6",
"lifetime_points_earned": 1200,
"lifetime_points_expired": 0,
"available_points": 1200,
"points_onhold": 10,
"lifetime_points_deducted": 0,
"lifetime_points_redeemed": 0,
"referral_URL": "https://shopsocially.com/ref/TES855D6",
"custom_attributes": {
"City_Name": "Paris",
"Marital_Status": "Married",
"Income_Source": "Service",
"Age_In_Years": "45",
"Gender_Identity": "Female",
"Graduation_Date": "15/12/1989 00:00:00"
},
"revenue": 1190,
"aov": 20,
"deleted_date": null
},
"referrer_info": {
"id": "63870ad3f9e076000b1ab907",
"first_name": "John",
"last_name": "Doe",
"email_address": "johndoe@gmail.com",
"address": {
"city": "Palo Alto",
"country": "US",
"line2": "530 Lytton Ave",
"line1": "Suite #200",
"state": "CA",
"postal_code": "94301"
},
"phone_number": "+1-6507017759",
"member_id": "john.doe23",
"member_status": "active",
"member_tags": [
"referrer",
"referred"
],
"number_of_purchases": 2,
"number_of_redemptions": 2,
"birthdate": "08/26/1989 00:00:00",
"enrollment_date": "11/30/2022 00:00:00",
"last_modified_date": "11/30/2022 00:00:00",
"first_purchase_date": "11/30/2022 00:00:00",
"instagram_handle": "www.instagram.com/john",
"last_purchase_date": "11/30/2022 00:00:00",
"anniversary_date": "05/03/2021 00:00:00",
"twitter_handle": "www.twitter.com/john",
"preferred_language": "English",
"tier_info": {
"current_period_start": "03/01/2022 00:00:00",
"loyalty_tier_name": "Max-Pro",
"qualified_points": 2380,
"loyalty_tier_id": "tier_cb4b5",
"current_period_end": "02/28/2023 23:59:59"
},
"referral_code": "SAM02XIU",
"lifetime_points_earned": 38035,
"lifetime_points_expired": 0,
"available_points": 12681,
"points_onhold": 100,
"lifetime_points_deducted": 0,
"lifetime_points_redeemed": 25354,
"referral_URL": "https://shopsocially.com/ref/SAM02XIU",
"custom_attributes": {
"City_Name": "Paris",
"Marital_Status": "Married",
"Income_Source": "Business",
"Age_In_Years": "35",
"Gender_Identity": "Male",
"Graduation_Date": "03/12/2000 00:00:00"
},
"revenue": 2380,
"aov": null,
"deleted_date": null
},
"referral_success_activity_info": {
"activity_id": "made_a_purchase",
"activity_name": "Purchase on website",
"order_info": {
"order_total": "600",
"currency": "USD",
"order_id": "order13401703",
"order_subtotal": "1190",
"reason": "reference",
"device_type": "desktop",
"coupons": "3199"
}
},
"referrer_reward_info": [
{
"id": "638718fcf9e076000ab268e4",
"transaction_type": "award",
"member_id": "johndoe55",
"transaction_attributes": {
"reason": "referredafriend",
"tags": []
},
"approver_details": {
"approver_id": null,
"approver_name": "System"
},
"approved_date": "11/30/2022 08:49:00",
"last_modified_date": "11/30/2022 08:49:00",
"created_date": "11/30/2022 08:49:00",
"award_info": {
"activity_id": "referral",
"activity_name": "Refer a Friend",
"points_status": "approved",
"points": 35645
},
"points_expiration_date": "12/10/2022 08:49:00",
"auto_approval_date": ""
},
{
"id": "638718fdf9e076000ab268f1",
"transaction_type": "coupon_award",
"member_id": "john.doe23",
"transaction_attributes": {
"reason": "reference",
"tags": []
},
"approver_details": {
"approver_id": null,
"approver_name": "System"
},
"approved_date": "11/30/2022 08:49:01",
"last_modified_date": "11/30/2022 08:49:01",
"created_date": "11/30/2022 08:49:01",
"award_info": {
"coupon_code": "34",
"activity_id": "referral",
"points": 0,
"points_status": "approved",
"activity_name": "Refer a Friend"
}
}
]
}
}
],
"created_date": "11/30/2022 08:49:01"
}Responses
| Status | Description |
|---|---|
200 | Acknowledges receipt of the events. Return 200 as soon as you receive the request and process the events afterwards, so the request doesn't time out. |
| Other | Any status code other than 200 is a failure: the request is sent again every 5 minutes until your endpoint returns 200 or the maximum number of attempts (5 by default) is reached. Your Customer Success Manager can change these settings. |