Table of Contents

How to Enable the Iterable Integration

Samantha Brown Updated by Samantha Brown

Friendbuy sends your referral and loyalty data to Iterable automatically, so you can personalize emails, SMS, push notifications, build segments, and trigger journeys without any custom code.

The integration sends two kinds of data:

  • Profile fields on each customer: name, referral link and code, QR code, share and referral counts, coupons, unredeemed reward value, points, tier and more.
  • Events when something happens: a share, a reward earned, a tier change, a receipt processed and more. These are sent right away and can trigger a journey.
Friendbuy will only send emails & phone numbers of Advocates and Friends who have opted in to receive email & SMS communication. They would need to check the opt-in checkboxes on Referral and Friend Incentive widgets.

Advocate and Friend email addresses will be added to two specific lists that are generated once the integration is enabled.

Before you start

Complete these three steps before installing. Step 2 is critical because data types of fields cannot be changed after established in Iterable.

  1. In Iterable, go to Integrations → API Keys and click New API Key. Name it (for example, "Friendbuy Integration Key"), choose the Server-side type, then click Copy and store the key somewhere secure. You can't view the full key again after closing the dialog; if you lose it, generate a new key and reinstall.
Make sure you save this in a secure location because once you click close, you will not be able to access the entire API key from your Iterable account.  You will need to generate a new API key and go through the steps to re-integrate Friendbuy. 
  1. Ask your Iterable CSM to create two user fields as type nested: friendbuyReferralLinks and friendbuyCoupons.
Iterable locks a field's type the first time data arrives, and it can't be changed later. The nested type lets you filter on individual items inside these lists (for example, "has an unredeemed coupon worth over $10"). If your project already has these fields as another type, everything else still works; only advanced filters on list items are unavailable.

Install and verify

Install

  1. In Friendbuy, go to Developer Center > Integrations > click on the Iterable tile.
  2. Paste your Iterable API key and click Install Integration.

Verify the connection

  1. Make a test share using a test email address from one of your live widgets tied to your Referral program.
  2. In Iterable, go to Audience → Lists and confirm the Friendbuy Advocates and Friendbuy Referred Friend lists appear.
  3. Open the test user's profile. You should see fields beginning with Friendbuy, including the referral link in friendbuy_purl.
  4. Open the user's Events tab. You'll see events such as Friendbuy - Referral Shared.
Existing customers: profiles are populated at each customer's next activity (a share, reward or purchase). Friendbuy does not bulk-backfill historical data.

Profile fields

Profile fields update user profiles and can be used in templates as merge variables, for example {{[Friendbuy Shares]}}.

Customer Profile Fields

Field

Example

Notes

Friendbuy Customer Name

Jane Doe

When available from first name and last name

Friendbuy Customer First Name

Jane

When available

Friendbuy Customer Last Name

Doe

When available

Friendbuy Customer Birthday

03-14

Month-day

name, phoneNumber

Jane Doe, +15555550123

Standard Iterable fields

$source

Friendbuy

Set only when Friendbuy first creates the user; never overwrites your value

Field

Example

Notes

friendbuy_purl

https://fbshare.me/ab12

Advocate's main referral link

Friendbuy Recently Used

{campaignName, referralLink, referralCode, createdAt, lastUsedAt}

Campaign the advocate shared most recently, including their referral code

friendbuyReferralLinks

List, one item per campaign (same shape as above)

Active campaigns only

Friendbuy QR Code Link

Link to a QR image

For the most recently used campaign

Friendbuy Google Wallet Link

Link

Only if you use Google Wallet passes

Friendbuy Apple Wallet Link

Link

Only if you use Apple Wallet passes

Friendbuy Shares

4

Total shares; 0 or more

Friendbuy Date of Last Share

2026-10-01T08:09:53.994Z

Friendbuy Successful Referrals

2

Friends who completed a qualifying purchase; 0 or more

Friendbuy Referred Purchases

3

Friendbuy Referred Revenue

1387.95

Friendbuy Referred Revenue Currency

USD

Coupons and rewards

Field

Example

Notes

friendbuyCoupons

List of {couponCode, value, currency, status, campaignName, distributedAt}

status is distributed or redeemed

Friendbuy Recent Coupon

Newest coupon (same shape as above)

Friendbuy Unredeemed Coupon Value

16

Total value of rewards not yet used

Friendbuy Rewards Redeemed

1

Number of rewards redeemed

couponCode, couponAmount, couponCurrency, couponStatus

SAVE20, 20, USD, distributed

Legacy fields, kept so existing templates keep working

Loyalty

Field

Example

Notes

Friendbuy Points Balance

120

Uses your program's points name, e.g. Friendbuy Stars Balance

Friendbuy Points Redeemed

20

Friendbuy Account Credit Balance

5

Only if you give account credit

Friendbuy Member Tier Name

Gold

Empty when the member is in no tier

Friendbuy Loyalty Opt-In Date

2026-10-01T05:47:54.799Z

Friendbuy Loyalty Opt-Back-In Date

2026-10-05T10:12:00.000Z

When a member re-joins

Friendbuy Success Receipts

3

Approved receipts

Events

Events are sent right away, and each one can start an Iterable journey.

Event

When it's sent

Data in the event

Friendbuy - Referral Created

An advocate gets a referral link

Campaign Name, Campaign ID, Advocate Name

Friendbuy - Referral Shared

An advocate shares

Campaign Name, Campaign ID, Share Channel (email, purl, facebook…), Advocate Name

Friendbuy - Advocate Reward Earned

An advocate earns a reward

Campaign Name, Campaign ID, Reward Code, Reward Value, Reward Currency, Order ID, Customer Name

Friendbuy - Friend Incentive Earned

A referred friend earns their reward

Same as above, plus Friend Name

Friendbuy - Loyalty Reward Earned from a Purchase

Points or credit for a purchase or receipt

Campaign Name, Campaign ID, Points (or Account Credit), Reward Value, Reward Currency, Order ID, Customer Name

Friendbuy - Loyalty Reward Earned from Joining Program

A member joins your loyalty program

Same as above

Friendbuy - Loyalty Reward Earned from Referring a Friend

Points for a referral

Same as above

Friendbuy - Loyalty Reward Earned from a Signup

Points for signing up

Same as above

Friendbuy - Loyalty Reward Earned from a Custom Event

Points for a custom action, such as a birthday

Same as above, plus Custom Event Name

Friendbuy - Member Tier Changed

A member reaches a tier or drops out of one

Tier Name (e.g. Gold); empty when they lose their tier

Friendbuy - Receipt Processed

A receipt is approved or rejected

Receipt ID, Customer ID, Store Name, Store ID, Amount, Status, Purchase Date, Submission Date, Product Count, Products, Rejection Reason (if rejected)

Reward events also include any custom purchase attributes you send to Friendbuy, such as subtotal.

Example payload for Friendbuy - Advocate Reward Earned:

{
  "Campaign Name": "Fall Campaign",
  "Reward Code": "SAVE20",
  "Reward Value": 20,
  "Reward Currency": "USD",
  "Order ID": "8334577139810",
  "Customer Name": "Priya Shah"
}

Building journeys

In Iterable, go to Journeys → New Journey, choose a Custom Event start, pick a Friendbuy event, then add actions such as Send Email or Send SMS steps. Common Journey flows:

Goal

Start with

Use in the message

Ask a new advocate to share

Referral Created

{{friendbuy_purl}}, {{[Friendbuy QR Code Link]}}

Thank an advocate for sharing

Referral Shared

{{[Advocate Name]}}, {{[Campaign Name]}}

You earned a reward

Advocate Reward Earned

{{[Reward Code]}}, {{[Reward Value]}}

Welcome a referred friend

Friend Incentive Earned

{{[Friend Name]}}, {{[Reward Code]}}

You earned points

Loyalty Reward Earned from a Purchase

{{Points}}, {{[Friendbuy Points Balance]}}

Tier up or tier lost

Member Tier Changed

Filter on Tier Name is empty → you lost your tier; otherwise → welcome to {{[Tier Name]}}

Receipt approved or rejected

Receipt Processed

{{Status}}, {{[Rejection Reason]}}

Profile fields also work in any Campaign, not just Journeys. For example, a monthly newsletter can show {{[Friendbuy Successful Referrals]}} and {{[Friendbuy Unredeemed Coupon Value]}} to remind advocates of rewards waiting to be used.

Data in Iterable

Opted in Advocate email addresses and phone numbers (optional) that are captured through your Referral Widgets will automatically display in the user profile under the Friendbuy Advocates list.

Sample Referral Widget (Burrow)

The referral link that was generated for a given Advocate will also be displayed  in their Iterable user profile.  Click on any email address in the Friendbuy Advocate Audience List to view their profile and locate the referral link under the friendbuy_purl field.

Referred Friend email addresses and optionally phone numbers that are captured from your Friend Incentive Widgets will automatically display in the user profile under the Friendbuy Referred Friend list. 

Sample Friend Incentive Widget (Burrow)

We will also display the coupon codes that were sent to Advocates and referred Friends and you can see this code if available under couponCode.  We will also display the status of the coupon code under CouponStatus.

The status will either say distributed if the coupon code was distributed to the user via Friendbuy, or redeemed, if the coupon code was redeemed at checkout.

Also, if you click on the email address, you can see the coupon code under Available User Fields 

FAQ

  • Lists: Friendbuy adds advocates to the Friendbuy Advocates list and referred friends to the Friendbuy Referred Friend list. They can be used in Iterable campaigns and journeys.
  • Opt-in: only contacts who opted in through your Friendbuy widget checkboxes are sent to Iterable.
  • Already using the Iterable integration? Your existing fields (friendbuy_purl, couponCode, couponStatus and the rest) keep working, so current templates don't need changes.
  • Only active campaigns appear in referral link fields. Draft, paused and ended campaigns are left out.
  • QR code and wallet links point to the advocate's most recently used campaign.
  • Project types: works with email-based, hybrid and userId-based Iterable projects. Friendbuy uses the customer's Friendbuy ID as the Iterable userId.
  • Invalid email addresses are rejected by Iterable and skipped.
  • No historical backfill: existing customers' fields fill in at their next activity.
  • Referral emails sent by Friendbuy still go out from the Friendbuy platform using your domain.
  • Uninstall: go to Developer Center → Integrations → Iterable and remove the integration. Friendbuy stops sending data; data already in Iterable remains.

How did we do?

Trigger a Direct Mail Campaign to Drive Referral Program Awareness (Friendbuy x Iterable x Poplar)

How to Automatically Text Referred Friends their Coupon Code with Iterable Journeys

Contact