Skip to main content

Generate and redeem a referral code

Prerequisites
Before you start, ensure you:
  1. Create your Integration API key.
  2. If you haven't done so already, fork our Sample Campaigns collection in Postman: Run in Postman.
  3. In the Campaign Manager, open the MEDIUM-REFERRAL: Generate and redeem a referral code demo campaign and click Activate Campaign.
  4. Open the Rule Builder to get some context.

Let's create a promotion rule that automatically creates a referral code when a customer registers. When this code is redeemed by a referred friend, the friend gets 50 loyalty points, and the advocate gets 100 points.

Creating the promotion​

In the current scenario, let's use 2 rules:

  1. Generate a referral code
  2. Friend redeems referral code

Rule 1: Generate a referral code​

We want to check when a customer registers, we should give them a referral code they can share with their friends.

  • Condition: Check for event types and custom event values and select Customer Profile Registration.
  • Effect: Create referral code and select In the current campaign.

A customer profile registration is a built-in event that happens when a new customer profile is created via the Update customer profile endpoint.

This customer is known as an Advocate because the referral code was generated in their session.

Rule 2: Friend redeems referral code​

We want to find a valid referral code, and when we find one, give 100 loyalty points to the advocate and 50 to the friend.

A referral code always contains the information about the customer related to the creation of the code.

  • Conditions:

    • Referral code is valid.
    • Check for default event: Customer Session Closing.

  • Effects:

    1. Add loyalty points:
      • Loyalty program: Sample wallet.
      • Recipient: Advocate.
      • Reason: 100 Bonus points for Advocate
      • Amount of points: 100
    2. Add loyalty points:
      • Loyalty program: Sample wallet.
      • Recipient: Current Customer (Friend).
      • Reason: 50 Bonus points for Friend
      • Amount of points: 50

Running the campaign​

To run the whole campaign, we need 2 requests to simulate the different stages.

A customer registers​

When a customer registers, they should get a referral code. The customer registration event is triggered by the Update Customer Profile endpoint with a new integration ID passed as a path parameter.

Let's assume the NEWCUSTOMER id doesn't exist yet and let's call the Update customer profile endpoint with it.

The payload can remain empty, we only need an integrationId and the runRuleEngine query parameter set to true.

Creating a new profile
CURL -X PUT https://mycompany.europe-west1.talon.one/v2/customer_profiles/NEWCUSTOMER?runRuleEngine=true -d
'{
  "attributes": {},
  "audiencesChanges": {
    "adds": [],
    "deletes": []
  },
  "responseContent": []
}'

Let's imagine that our customer received their referral code and gave it to a friend.

A friend places an order​

Our first customer's friend places an order containing the referral code. Let's test creating this session, using the Update customer session endpoint:

To trigger the rule, we must send a valid referral code.

Sending a session update
CURL -X PUT https://mycompany.europe-west1.talon.one/v2/customer_sessions/68476946 -d
'{
  "customerSession": {
    "profileId": "673TGNRP35",
    "state": "open",
    "cartItems": [
      {
        "name": "ProductC",
        "sku": "sku-00004",
        "quantity": 1,
        "price": 100,
        "Category": "Accessories",
        "weight": 0,
        "position": 0,
        "attributes": {}
      }
    ],
    "couponCodes": [
      ""
    ],
    "referralCode": "JY9P-HYL8",
    "attributes": {},
    "additionalCosts": {}
  },
  "responseContent": []
}'
Key Takeaways
  • A referral consists of an advocate who refers a friend.
  • You can use many rules in one campaign. A request can trigger several rules at once, or you might need specfic requests. This depends on your conditions.
  • You can trigger the rules with the Update customer profile endpoint, as well as the Update customer session endpoint.
  • You can reserve coupons for a specific customer.