The Voucherify Developer Hub

Welcome to the Voucherify developer hub. You'll find comprehensive guides and documentation to help you start working with Voucherify as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Referral program

Learn how to set up a referral program and create unique referral codes in the campaign manager.

To begin with, you’ll need to run the Campaign manager with the Plus.

When the creator is ready, you can configure program details. Let's go through each stage of the manager step by step.

Firstly, add a new referral campaign.

Step 1: Program details

In the first step, define program details such as:

  • program name
  • code settings (pattern, redemption limit)
  • auto-update campaign mode

Click on the NEXT STEP when it's ready.

Step 2: Time limits

In the 2nd step, define optional time limits - add a campaign timeframe, days of the week or recurring periods when referral codes are active (you can read about all time limits for vouchers here. When ready, go to the NEXT STEP.

Step 3: Conversion type

The 3rd section 'Referee reward' consists of the following steps:

1. Choose a conversion event (when a new customer is approved as a referred):

  • If you want to define 'referred' customer based on referral codes redemptions choose the first checkbox
  • You can also define 'referred' customers based on a custom event defined previously in your Project Settings, for example, 'customer_subscribed' event. As a result, if a new customer performs defined event he/she will be counted as a referred customer and the owner of the referral code used during the event gets new referred customer attached to his/her account.

Event Schema

To define custom events go to the Project Settings and add the respective configuration - Read step by step guide. Please note that your application must store an event describing a moment of conversion once you approve a new customer as a referred person. It triggers a rewarding mechanism.

Look below to see example POST API request with a custom event defined.

POST /events

{
  "event": "signed_up",
  "customer": {
    "source_id": "tom+referrer_3_4@voucherify.io",
    "email": "tom+referrer_3_4@voucherify.io",
    "name": "Tomasz Pindel",
    "metadata": {
    	"test": true
    }
  },
  "metadata": {
	"sign_up_date": "2019-01-25T14:30:00.000Z"
  },
  "referral": {
  	"code":"NRY"
  }
}

After you mark respective checkbox and define the conversion event, you need to choose a type of your referral program.

2. Choose between single- and double-sided referral program
Decide if the new customer (referee) and referrer will be rewarded - double-sided program, or if only the referrer gets the reward -single-sided program.

If you mark a checkbox with a double-sided referral program, you need to define a reward for new customers (referees). It can be a percent, amount or unit discount code. When ready, click on NEXT STEP.

If you marked a checkbox with a single-sided referral program, you can go straight to the NEXT STEP.

Step 4: Validation rules for referral codes

4th stage of the manager enables you to create validation rules attached to referral codes. They restrict redemptions made by new customers (referees). To add your rules choose CREATE and Add a name for validation rules. If you need help with creating limits, visit this guide.
Confirm your rules by choosing SAVE and go to the NEXT STEP

Step 5: Rewarding criteria

In the 5th stage of the program creation, you need to define rewarding criteria and tell Voucherify when the referrer is rewarded.

Dependently on which conversion event you've chosen in the 3rd section, you can specify the number of redemptions or number of customers who perform the specific action that qualifies referrer for a reward.

1. Conversion event - referral code redemption

  • Reward every time referee redeems the referral code - every time referral code is used, the reward is triggered.

Remaining options, listed below, limit reward triggering to one per new customer. It means that referrer cannot get a reward two times if both redemptions come from the same "new" customer (referee).

  • Only first time referee redeems code AND the referrer customer segment is [choose one of your existing segments]. This option enables you to limit referrers who can apply for a reward to one of your existing customer segments.

  • Only first time referee redeems code AND the referrer customer segment is in NEW SEGMENT created below. This option enables you to build a segment that defines rewarding criteria. Typically, it's a segment based on the number of referred customers. (Segment of referrers who get the reward can have multiple rules and limits built with available filters).

When the respective checkbox is set, click on NEXT STEP and define the reward for referrers. You can choose from:
* your existing campaigns (chosen campaign should be in auto-update mode!)
* creating a new campaign of rewards from scratch

2. Conversion event - custom event

If you count referred customers (referees) based on the performed event, defined in the 3rd section, you can choose from:

  • Rewarding referrer every time the referee performs a specific action (custom conversion event).
  • Defining a number of referees who need to perform a specific action to trigger a reward for the referrer.

Additionally, if you expand ADVANCED options, you can add more limits and rules that referrer needs to meet to get the reward.

For example, you can set that beside that 2 customers need to perform the chosen custom event with referrer's code, referrer has to have more than 2 orders made in your store so far to get the reward.

When the rewarding criteria are set, click on NEXT STEP and define the reward for referrers. You can choose from:
* your existing campaigns (chosen campaign should be in auto-update mode!)
* creating a new campaign of rewards from scratch

Trigger action

Lastly, in this stage, you need to define what happens when a referrer meets the reward criteria. You can choose from:
* HTTP callout (add specific URL for notification)
* MailChimp (Integrations)
* Email (the manager lets you design the message template)
* SMS (the manager lets you design the message template)

When the action is defined, you can follow to the 6th stage or choose to ADD TIER. What are 'tiers' and why do you need them?

Tiers

Each tier is a separate level in your referral program. If you want to have different rewards or/and different rewarding criteria then tiers are what you need. For example, tier 1 can reward each referrer who refers at least 1 customer with $5 gift card; tier 2 can reward each referrer who refers at least 3 customers with 30% discount.

There is no limit on a number of tiers, you can make multi-level referral programs with many rewards and custom rewarding schemas.

Step 6: Metadata

In the 6th stage, you can add optional metadata attributes

The last stage of the manager shows you a summary of your referral program. You can see the overview and, in case you need to, go back to each step to set it up again. When all program details are ready, confirm with SAVE CAMPAIGN and wait until the codes are generated.

Now you can distribute the codes to your customers. To do so, you can use publish method explicitly or set up a Distribution to deliver codes automatically. It gets a valid code from the campaign and marks it as a published one, so the same code is never used again.

Referral program: ultimate guide

In this guide, you can see the entire referral workflow, starting from inviting referrers to join a campaign and ending up on how new customers can use referral codes.

The key thing is to pass the customer information along in the request’s body. Then, the code gets assigned and the customer becomes either persisted as a customer entity or updated if he's already there.

{
  "campaign": "referral-program-01", // the campaign we’ve just created
  "customer": {
    "email": "erlich@bachmanity.com",
    "name": "Erlich Bachman"
  }
}
{
  "code": "80Pvtbem",
  "campaign": "friends-refer-friends",
  "category": null,
  "type": "DISCOUNT_VOUCHER",
  "discount": {
    "type": "PERCENT",
    "percent_off": 10
  },
  "gift": null,
  "start_date": null,
  "expiration_date": null,
  "publish": {
    "object": "list",
    "count": 1,
    "data_ref": "entries",
    "entries": [
      {
        "customer_id": "cust_clIUkWbQxCrIjr9KQyMAMHxE",
        "customer": null,
        "channel": "API",
        "published_at": "2017-01-25T14:26:24Z",
        "metadata": null
      }
    ]
  },
  "redemption": {
    "object": "list",
    "total": 0,
    "data_ref": "redemption_entries",
    "quantity": null,
    "redeemed_quantity": 0,
    "redemption_entries": []
  },
  "active": true,
  "additional_info": null,
  "metadata": null,
  "is_referral_code": true,
  "referrer_id": "cust_clIUkWbQxCrIjr9KQyMAMHxE"
}

Example source code

You can take a look at the exemplary referral program integration in the Examples.

Once you call the publish method, you can see the footprint in the dashboard.

Assigning the code to the customer.

Assigning the code to the customer.

From this moment, every time someone redeems a referral code from the campaign, one of the gift cards from the campaign is going to be pushed out as a reward.

Ensure unique customers

To count a referred customer as valid one you have to provide a customer object with unique source_id when calling redeem.

This is achieved with the invocation of the webhook. The call will store the information about the gift card:

See an example of referral webhook call below

See an example of referral webhook call below

Other reward delivery methods

Instead of a webhook callout, you can send the reward via email or with SMS straight from Voucherify.

In the payload, you’ll get all the details of this event, including the reward for the referrer (in our case a gift card code). Then, you can handle such a callout as you want: e.g. send a gift card by email SMS or print it out and deliver by snail mail.

This is it! You can go to campaigns view to monitor the success rate of the campaign.

For more examples visit the referral program section in the Help Center.

Webhook example

{
   "id":"event_QVQp8HzTHY41r5EEpualSZgZuKXgxV",
   "object":"event",
   "webhook_id":null,
   "project_id":"proj_s0m3pr0J3Ct",
   "created_at":"2017-08-21T07:36:37.632Z",
   "type":"customer.rewarded",
   "data":{
      "object":{
         "id":"cust_R9aWTKCxDV4f11A76XrbPZBb",
    		"source_id":"customer99",
         "name":"Erlich Bachman",
         "description":null,
         "email":"erlich@bachmanity.com",
         "phone":null,
         "birthday":null,
         "address":{
            "line_1":null,
            "country":null,
            "line_2":null,
            "city":null,
            "state":null,
            "postal_code":null
         },
         "summary":{
            "orders":{
               "total_count":0,
               "total_amount":0,
               "average_amount":0,
               "last_order_date":null,
               "last_order_amount":0
            },
            "redemptions":{
               "gift":{
                  "amount_to_go":1400,
                  "redeemed_amount":0
               },
               "total_failed":0,
               "total_redeemed":0,
               "total_succeeded":0,
               "total_rolled_back":0,
               "total_rollback_failed":0,
               "total_rollback_succeeded":0
            }
         },
         "loyalty":{
            "points":0,
            "campaigns":{
               "rewardEveryRedemption":{
                  "referred_customers":0
               }
            },
            "referred_customers":0
         },
         "metadata":null,
         "system_metadata":null,
         "created_at":"2017-08-21T07:23:34.579Z",
         "object":"customer"
      },
      "related_object":{
         "code":"JXR3zxfD",
         "campaign":"referrerRewards",
         "category":null,
         "type":"GIFT_VOUCHER",
         "discount":null,
         "gift":{
            "amount":700,
            "balance":700
         },
         "start_date":null,
         "expiration_date":null,
         "publish":{
            "object":"list",
            "count":1,
            "url":"/v1/vouchers/JXR3zxfD/publications?page=1&limit=10"
         },
         "redemption":{
            "object":"list",
            "quantity":1,
            "redeemed_quantity":0,
            "redeemed_amount":0,
            "url":"/v1/vouchers/JXR3zxfD/redemptions?page=1&limit=10"
         },
         "active":true,
         "additional_info":null,
         "metadata":null,
         "is_referral_code":false,
         "updated_at":"2017-08-21T07:36:35Z",
         "assets":{}
      }
   },
   "metadata":{
      "is_rewarded":true,
      "source":{
         "tier_name":"Some tier",
         "object_id":"rewardEveryRedemption",
         "object_type":"campaign"
      }
   }
}

Referral program


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.