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 Product docs.

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 two 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/expiration date and link the referral code to a customer profile.

note

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 referral code for an advocate endpoint with this example payload that creates a referral code for customer 88:

curl https://example.talon.one/v1/referrals \
-X POST \
-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 time zone

Pay attention to the startDate and expiryDate properties. They use the RFC3339 format. They can contain any time zone, relative to UTC. In this case, the time zone is EST, or UTC-5. You can provide any time zone (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 effect.

Whenever this rule gets executed successfully, the Integration API returns the referralCreated effect. It contains the referral code generated.

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 https://example.talon.one/v2/customer_sessions/C156902 \
  -X PUT \
  -d '{
  "profileId": "35",
  "referralCode": "kg5yldcv1i"
  }'

Once submitted, check wether Talon.One accepted or rejected the referral code by looking for the following effects in the response: