Skip to main content

Creating referral programs

A referral program is defined by an advocate, a friend and a referral code.

  • The advocate is the person who invited their friend via a referral program.
  • The friend is the person who receives the invite from an advocate.
  • The referral code is a generated code that can be used by one or more friends.

To learn more about what referral programs are, see the end-user documentation.

Understanding the context#

Let's imagine we want to set up a referral program for our business in Boston, USA. The program should give a referral code to every customer in the database that they can share with their friends.

Setting up a referral program#

Before we begin, let's suppose we have a campaign with the referral and coupon features active.

To set up a referral program, we must generate referral codes for our customers. We can do this in 2 ways:

Both methods as they offer different benefits.

Using the endpoint#

The endpoint allows us to create referral codes directly instead of updating customer sessions. We can also set a start/expiry date and link the referral code to a customer profile.


Another option is to link the referral code to a friend, which is useful when you're migrating historical referral campaigns to Talon.One.

Let's call the Create a referral code endpoint with this example payload that creates a referral code for customer 88:

curl \
-d '{
"advocateProfileIntegrationId": "88",
"campaignId": 58,
"startDate": "2020-02-12T15:22:48.351041-05:00",
"expiryDate": "2020-05-28T15:22:48.351041-05:00",
Note about the timezone

Pay attention to the startDate and expiryDate properties. They use the RFC3339 format. They can contain any timezone, relative to UTC. In this case, the timezone is EST, or UTC-5. You can provide any timezone (your own, your store's, your app's...), it is converted to UTC internally.

We can repeat this operation for each customer of our database to give them a referral code.

Using a Rule Builder effect#

Let's now imagine that we have more than one loyalty campaign in our application. In this case we want to choose in which campaign the referral code can be redeemed. To do this, we must use the Rule Builder in the Campaign Manager and create an effects.

Whenever this rule gets executed successfully, the integration API returns a referralCreated effect that also contains the referral code generated:

"referralCreated", // effect type
"REFERRALCODE", // referral code
"friendProfileIntegrationId" // Customer profile ID for the customer that can redeem this referral code

Communicating referral codes to Talon.One#

When a user inputs a referral code in your application, share it with Talon.One using the Update Customer Session endpoint.

For example, submitting the kg5yldcv1i referral code for the profile with id 35:

curl \
-X PUT \
-d '{
"profileId": "35",
"referral": "kg5yldcv1i"

Once submitted, you can check wether Talon.One accepted or rejected the referral code by looking for the acceptReferral or rejectReferral effect in the response:

"acceptReferral", // effect type
"kg5yldcv1i" // referral code