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

  1. From your workspace’s Sources catalog page click Add Source.
  2. Search for “Friendbuy” in the Sources Catalog, select Friendbuy, and click Add Source.
  3. 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).
  4. Click Add Source to save your settings.
  5. 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 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 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 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 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 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 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 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 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 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



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account