Friendbuy Source
Good to know: Event Cloud source
The Friendbuy Source is an event source. This means that it sends data as events, which are behaviors or occurrences tied to a user and a point in time. Data from these sources can be loaded into your Segment warehouses, and also sent to Segment streaming destinations. Learn more about cloud sources.
Friendbuy sends referral and loyalty event data to Segment in real time, allowing you to send data instantly to connected tools like your data warehouse. This enables timely and up-to-date insights, personalized user experiences, and customer cohort analysis.
This source is maintained by Friendbuy. For any issues with the source, contact their Support team.
Getting Started
- From your workspace’s Sources catalog page click Add Source.
- Search for “Friendbuy” in the Sources Catalog, select Friendbuy, and click Add Source.
-
On the next screen, give the Source a nickname configure any other settings.
- The nickname is used as a label in the Segment app, and Segment creates a related schema name in your warehouse. The nickname can be anything, but we recommend using something that reflects the source itself and distinguishes amongst your environments (eg. Friendbuy_Prod, Friendbuy_Staging, Friendbuy_Dev).
- Click Add Source to save your settings.
- Copy the Write Key from the Segment UI and log in to your Friendbuy account - navigate to Settings > Developer Center > Integrations > Select Segment Integration and paste the Write Key. Click Install.
Stream
Friendbuy uses our Segment Integration to stream event data to Segment in real time. It uses the server-side track
and identify
methods to send data to Segment. These events are then available in any destination that accepts server-side events, and available in a schema in your data warehouse, so you can query using SQL.
Friendbuy includes an Anonymous ID (a hashed email) for every event. Friendbuy also includes a User ID, which in Friendbuy is the Customer ID. If Friendbuy does not have the Customer ID, then only the Anonymous ID is included.
Referral Events
The table below lists referral events that Friendbuy sends to Segment. These events appear as tables in your warehouse, and as regular events in other Destinations. Friendbuy always includes the Anonymous ID and includes the User ID if available.
Event Name | Description |
---|---|
Advocate Created | Segment receives this event when a customer submits their name, email and/or phone number in a Referral Widget on your site |
Referred Friend Created | Segment receives this event when a customer is referred by and Advocate and submits their name, email and/or phone number in a Friend Widget on your site |
Referral Share | Segment receives this event when an advocate shares the referral program offer through the Referral Widget with a Friend via Email, PURL, SMS or Social (Facebook, Messenger, Twitter) |
Referral Advocate Reward Earned | Segment receives this event when an Advocate earns a reward after a referred Friend completes the referral conversion event and passes all business rules and fraud checks |
Referral Friend Incentive Earned | Segment receives this event when a referred Friend completes the referral conversion event, passes all business rules and fraud checks, and then earns an incentive |
Referral Advocate Reward Rejected | Segment receives this event when an Advocate reward is rejected and not distributed because they did not passes all business rules and fraud checks |
Referral Friend Incentive Rejected | Segment receives this event when a referred Friend completes the referral conversion event, but does not pass all business rules and fraud checks, and incentive is not distributed |
Loyalty Events
The table below lists loyalty events that Friendbuy sends to Segment. These events appear as tables in your warehouse, and as regular events in other Destinations. Friendbuy always includes the Anonymous ID and includes the User ID if available.
Event Name | Description |
---|---|
Loyalty Reward Earned | Segment receives this event when a Loyalty Member completes a rewardable event, passes all associated earning event rules, and earns a reward |
Loyalty Credit Earned | Segment receives this event when there is an update to a Loyalty Member’s credit. For example, when a Friendbuy Loyalty Credit is redeemed |
Referral Event Properties
The tables below list the properties included in each referral event.
Advocate Created
Property Name | Description | Always Included |
---|---|---|
Email address of the Advocate created | ✅ | |
phone | Phone number of the Advocate created | ✅ |
customer_id | Customer ID of the Advocate created. This will be the same value as the User ID that Segment receives for this event | ✅ |
ip | IP address of the Advocate created | ✅ |
referral_link | Referral link assigned to the Advocate created. A Referral link, also called a personal referral link or personal URL (PURL), is a link that uniquely associates an advocate to a referral program. An advocate uses their personal referral link to refer friends to a site or business. When this link is clicked by a friend, the friend is taken to the associated destination URL. Also, the referred friend’s browser will be cookied by Friendbuy with information about the referral |
✅ |
referral_code | Referral code assigned to the Advocate created. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign |
✅ |
campaign_name | The name of the referral campaign associated with the Referral Widget that was used to create this Advocate | ✅ |
campaign_id | The ID of the referral campaign associated with the Referral Widget that was used to create this Advocate | ✅ |
customer_name | Name of the Advocate created | Only included if known. This will be the full name if known. Otherwise, it might just be first name, depending on how the widget is configured or what the customer provides |
widget_name | The name of the Referral Widget that was used to create the Advocate | ✅ |
ab_test_variant_id | The ID of the variant used | Only included if the referral campaign is running an A/B test |
email_marketing_opt_in_status | The email subscription status of the Advocate created | ✅ |
sms_marketing_opt_in_status | The SMS subscription status of the Advocate created | ✅ |
Referred Friend Created
Property Name | Description | Always Included |
---|---|---|
Email address of the Friend created | ✅ | |
phone | Phone number of the Friend created | ✅ |
customer_id | Customer ID of the Friend created. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Friend created | ✅ |
advocate_referral_code | Referral code of the Advocate who referred this Friend. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. |
✅ |
A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign | ||
campaign_name | The name of the referral campaign associated with the Friend Widget that was used to create this Friend | ✅ |
campaign_id | The ID of the referral campaign associated with the Friend Widget that was used to create this Friend | ✅ |
customer_name | Name of the Friend created | Only included if known. This will be the full name if known. Otherwise, it might just be first name depending on how the widget is configured or what the customer provides |
widget_name | The name of the Friend Widget that was used to create this Friend | ✅ |
ab_test_variant_id | The ID of the variant used | Only included if the referral campaign is running an A/B test |
email_marketing_opt_in_status | The email subscription status of the Friend created | ✅ |
sms_marketing_opt_in_status | The SMS subscription status of the Friend created | ✅ |
Referral Share
Property Name | Description | Always Included |
---|---|---|
Email address of the Advocate | ✅ | |
phone | Phone number of the Advocate | ✅ |
customer_id | Customer ID of the Advocate. This will be the same value as the User ID that Segment receives for this event |
✅ |
share_channel | The share channel used by the Advocate. An advocate can refer a friend through several different channels, including email, personal referral link (PURL), SMS, or social channels like Facebook, Messenger, Twitter or WhatsApp |
✅ |
referral_link | Referral link assigned to the Advocate. A Referral link, also called a personal referral link or personal URL (PURL), is a link that uniquely associates an advocate to a referral program. An advocate uses their personal referral link to refer friends to a site or business. When this link is clicked by a friend, the friend is taken to the associated destination URL. |
✅ |
email_share_reminder | Indicates whether the Advocate chose to send the Friend a reminder email after 3 days | Only included if the share channel is email |
referral_code | Referral code assigned to the Advocate. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign |
✅ |
campaign_name | The name of the referral campaign associated with this referral share | ✅ |
campaign_id | The ID of the referral campaign associated with this referral share | ✅ |
widget_name | The name of the Referral Widget that was used to create this referral | ✅ |
ab_test_variant_id | The ID of the variant used | Only included if the referral campaign is running an AB test |
Referral Advocate Reward Earned
Property Name | Description | Always Included |
---|---|---|
Email address of the Advocate | ✅ | |
customer_id | Customer ID of the Advocate. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Advocate that earned the reward | ✅ |
coupon_code | The code used to receive a discount on a purchase, commonly set up as a percentage or dollar amount off an item. In a refer-a-friend program, a coupon code can be used to reward advocates or incentivize friends to make a purchase. The code can also be used to establish attribution between the referred friend and the advocate | Only included if the reward type is Coupon Code |
reward_value | The value of the reward earned by the Advocate | ✅ |
reward_currency | The currency of the reward earned by the Advocate | ✅ |
campaign_name | The name of the referral campaign associated with this Advocate reward | ✅ |
campaign_id | The ID of the referral campaign associated with this Advocate reward | ✅ |
conversion_event | The type of event the Friend needed to perform in order for the Advocate to earn this reward (e.g., purchase, email capture, sign up, or custom event) | ✅ |
friend_email | The email address of the Friend who performed the referral conversion event | ✅ |
friend_customer_id | Customer ID of the Friend who performed the referral conversion event | ✅ |
friend_ip_address | IP address of the Friend who performed the referral conversion event | ✅ |
friend_purchase_total | The total amount that the Friend spent at the time of conversion | Only included if the conversion_event is a purchase |
friend_order_id | The Order ID of the purchase that the Friend made at the time of conversion | Only included if the conversion_event is a purchase |
friend_new_customer_status | Indicates whether the Friend is a new customer | Only included if the conversion_event is a purchase |
reward_tier | The Reward Tier of the Advocate | Only included if you have set up Tier-based rewards |
widget_name | The name of the Referral Widget that the Advocate used to share | ✅ |
ab_test_variant_id | The ID of the variant used | ✅ |
share_channel | The share channel used by the Advocate. An advocate can refer a friend through several different channels, including email, personal referral link (PURL), SMS, or social channels like Facebook, Messenger, Twitter or WhatsApp |
✅ |
referral_code | Referral code assigned to the Advocate. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign |
✅ |
Referral Friend Incentive Earned
Property Name | Description | Always Included |
---|---|---|
Email address of the Friend that earned the incentive | ✅ | |
customer_id | Customer ID of the Friend that earned the incentive. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Friend that earned the incentive | ✅ |
coupon_code | The coupon code provided to the Friend, in order to incentivize them to make a purchase. A code used to receive a discount on a purchase, commonly set up as a percentage or dollar amount off an item. The code can also be used to establish attribution between the referred friend and the advocate |
Only included if the reward type is Coupon Code |
incentive_value | The value of the incentive earned by the Friend | ✅ |
incentive_currency | The currency of the incentive earned by the Friend | ✅ |
campaign_name | The name of the referral campaign associated with this Friend incentive | ✅ |
campaign_id | The ID of the referral campaign associated with this Friend incentive | ✅ |
conversion_event | The type of event the Friend needed to perform, in order for the Advocate to earn a reward (e.g., purchase, email capture, sign up, or custom event) | ✅ |
incentive_tier | The Reward Tier of the Advocate | Only included if you have set up Tier-based rewards |
ab_ test_variant_id | The ID of the variant used | Only included if the referral campaign is running an AB test |
share_channel | The share channel used by the Advocate. An advocate can refer a friend through several different channels, including email, personal referral link (PURL), SMS, or social channels like Facebook, Messenger, Twitter or WhatsApp |
✅ |
referral_code | Referral code assigned to the Advocate. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign. |
✅ |
advocate_email | The email address of the Advocate who referred the Friend that earned this incentive | ✅ |
advocate_customer_id | The Customer ID of the Advocate who referred the Friend that earned this incentive | ✅ |
advocate_ip_address | The IP address of the Advocate who referred the Friend that earned this incentive | ✅ |
widget_name | The name that the referred Friend used to enter their information to receive their incentive | ✅ |
friend_purchase_total | The total amount that the Friend spent at the time of conversion | Only included if the conversion_event is a purchase |
friend_order_id | The Order ID of the purchase that the Friend made at the time of conversion | Only included if the conversion_event is a purchase |
friend_new_customer_status | Indicates whether the Friend is a new customer | Only included if the conversion_event is a purchase |
Referral Advocate Reward Rejected
Property Name | Description | Always Included |
---|---|---|
Email address of the Advocate | ✅ | |
customer_id | Customer ID of the Advocate. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Advocate that earned the reward | ✅ |
rejection_reasons | The reason or reasons that this Advocate reward was rejected. This could be due to one or more business rules not being passed, such as a Friend who completed a conversion but did so outside of an established attribution window. This could be due to fraud detection, such as the referred Friend and the Advocate sharing the same IP address. |
✅ |
campaign_name | The name of the referral campaign associated with this Advocate reward | ✅ |
campaign_id | The ID of the referral campaign associated with this Advocate reward | ✅ |
conversion_event | The type of event the Friend needed to perform in order for the Advocate to earn this reward (e.g., purchase, email capture, sign up, or custom event) | ✅ |
friend_email | The email address of the Friend who performed the referral conversion event | ✅ |
friend_customer_id | Customer ID of the Friend who performed the referral conversion event | ✅ |
friend_ip_address | IP address of the Friend who performed the referral conversion event | ✅ |
friend_purchase_total | The total amount that the Friend spent at the time of conversion | Only included if the conversion_event is a purchase |
friend_order_id | The Order ID of the purchase that the Friend made at the time of conversion | Only included if the conversion_event is a purchase |
friend_new_customer_status | Indicates whether the Friend is a new customer | Only included if the conversion_event is a purchase |
reward_tier | The Reward Tier of the Advocate | Only included if you have set up Tier-based rewards |
widget_name | The name of the Referral Widget that was used to refer the Friend that converted | ✅ |
ab_test_variant_id | The ID of the variant used | Only included if the referral campaign is running an AB test |
share_channel | The share channel used by the Advocate. An advocate can refer a friend through several different channels, including email, personal referral link (PURL), SMS, or social channels like Facebook, Messenger, Twitter, or WhatsApp |
✅ |
referral_code | Referral code assigned to the Advocate. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign. |
✅ |
Referral Friend Incentive Rejected
Property Name | Description | Always Included |
---|---|---|
Email address of the Friend that had the incentive rejected | ✅ | |
customer_id | Customer ID of the Friend that had the incentive rejected. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Friend that had the incentive rejected | ✅ |
rejection_reasons | The reason or reasons that this Friend incentive was rejected. This could be due to one or more business rules not being passed, such as the Friend needing to be a new customer or needing the purchase to be a certain minimum order amount. This could be due to fraud detection, such as the referred Friend and the Advocate sharing the same IP address. |
✅ |
campaign_name | The name of the referral campaign associated with this Friend incentive | ✅ |
campaign_id | The ID of the referral campaign associated with this Friend incentive | ✅ |
conversion_event | The type of event the Friend needed to perform in order for the Advocate to earn a reward (e.g., purchase, email capture, sign up, or custom event) | ✅ |
reward_tier | The Reward Tier of the Advocate | Only included if you have set up Tier-based rewards |
ab_test_variant_id | The ID of the variant used | Only included if the referral campaign is running an AB test |
share_channel | The share channel used by the Advocate. An advocate can refer a friend through several different channels, including email, personal referral link (PURL), SMS, or social channels like Facebook, Messenger, Twitter, or WhatsApp |
✅ |
referral_code | Referral code assigned to the Advocate. A referral code is a unique code generated by Friendbuy to associate an advocate to a referral campaign. A referral code can be used to look up the advocate’s name, the advocate’s customer ID, and offer information for that particular referral campaign. Note: referral code is not a coupon code. It solely provides information to associate the advocate to a campaign. |
✅ |
advocate_email | The email address of the Advocate who referred the Friend that earned this incentive | ✅ |
advocate_customer_id | The Customer ID of the Advocate who referred the Friend that earned this incentive | ✅ |
advocate_ip_address | The IP address of the Advocate who referred the Friend that earned this incentive | ✅ |
widget_name | The name of the Referral Widget that was used to refer the Friend that converted | ✅ |
friend_purchase_total | The total amount that the Friend spent at the time of conversion | Only included if the conversion_event is a purchase |
friend_order_id | The Order ID of the purchase that the Friend made at the time of conversion | Only included if the conversion_event is a purchase |
friend_new_customer_status | Indicates whether the Friend is a new customer | Only included if the conversion_event is a purchase |
Loyalty Event Properties
The tables below lists the properties included in each loyalty event.
Loyalty Reward Earned
Property Name | Description | Always Included |
---|---|---|
Email address of the Loyalty Member | ✅ | |
customer_id | Customer ID of the Loyalty Member. This will be the same value as the User ID that Segment receives for this event |
✅ |
ip | IP address of the Loyalty Member | ✅ |
earning_event | The name of the event the Loyalty Member needed to perform in order to earn this reward (e.g., Joined Program, Purchase, Refer a Friend, Sign Up, or Custom Event) | ✅ |
friend_email | The email address of the Friend who performed the referral conversion event | Only included for “refer a friend” type earning events |
friend_customer_id | The Customer ID of the Friend who performed the referral conversion event | Only included for “refer a friend” type earning events |
friend_ip_address | The IP address of the Friend who performed the referral conversion event | Only included for “refer a friend” type earning events |
coupon_code | The coupon code provided to the Loyalty Member in order to redeem this reward. A code used to receive a discount on a purchase, commonly set up as a percentage or dollar amount off an item |
Only included if the reward type is Coupon Code |
reward_value | The value of the reward earned by the Loyalty Member | ✅ |
reward_currency | The currency of the reward earned by the Loyalty Member | ✅ |
campaign_name | The name of the loyalty campaign associated with this loyalty reward | ✅ |
campaign_id | The ID of the loyalty campaign associated with this loyalty reward | ✅ |
order_id | The Order ID of the purchase that the Loyalty Member made, which created this rewardable event | Only included if the conversion_event is a purchase |
purchase_total | The total amount spent by the Loyalty Member on the purchase that created this rewardable event | Only included if the conversion_event is a purchase |
birthday | The birth date of the Loyalty Member | Only included if known |
Loyalty Credit Event
Property Name | Description | Always Included |
---|---|---|
Email address of the Loyalty Member | ✅ | |
customer_id | Customer ID of the Loyalty Member. This will be the same value as the User ID that Segment receives for this event |
✅ |
earning_event | The type of event the Loyalty Member performed in order to earn this reward (e.g., Joined Program, Purchase, Refer a Friend, Sign Up, or Custom Event) | Only included if the credit_event_type is earned |
credit_amount | The amount of the update to the Loyalty Member’s credit | ✅ |
reward_currency | The currency of the update to the Loyalty Member’s credit | ✅ |
customer_running_balance | The current balance of the Loyalty Member’s credit | ✅ |
credit_event_type | The type of update to the Loyalty Member’s credit (e.g., earned, redeemed, expired, reversed) | ✅ |
credit_issuer | The email address of the Friendbuy user who manually issued the credit | Only sent if credit is issued manually |
credit_description | The description provided when a credit is manually issued | Only sent if credit is issued manually and the description field is filled in |
Adding Destinations
Now that your Friendbuy Source is set up, you can connect it to Destinations.
Log into your downstream tools and check to see that your events appear as expected, and that they contain all of the properties you expect. If your events and properties don’t appear, check the Event Delivery tool, and refer to the Destination docs for each tool for troubleshooting.
If there are any issues with how the events are arriving to Segment, contact the Friendbuy support team.
This page was last modified: 27 Oct 2023
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!