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

Loyalty program

In this tutorial, you’ll learn how to use Voucherify API to build a point-based loyalty program.

👍

Recommended

Read the loyalty program user guide to get an overview this campaign.

Prerequisites

To create a loyalty campaign you need 2 prerequisites:

  • Events which enable customers to collect points
  • Campaigns which will serve as rewards

We’ll use events to describe earning rules (how your customers can collect points) and campaigns, respectively, to define available rewards.

Earning events

Voucherify accepts 3 event types as options for points making:

  • a customer entered a segment
  • order paid event
  • custom event
    The loyalty campaign will detect the first 2 events automatically - when a customer enters a segment or when any of customer’s orders will be changed to PAID.

To trigger the 3rd option, we need specifically tell it so. We can achieve it with the Track Custom Event endpoint.

{
  "event":"submit_review",
  "customer":{
    "source_id":"[email protected]"
  },
  "metadata":{
    "url":"http://example.com/reviews/ACM3",
    "rank":5
  }
}

📘

Event schema

To use a custom event in a loyalty program, we need to define it in the Schema beforehand.

Creating rewards

To define a reward’s pool, you can tap into Voucherify’s discount campaigns. While creating a new loyalty campaign with the Dashboard, you can tap into existing discount coupons and gift cards or you can create a new one on the fly.

With the API, you can create a reward object with a dedicated endpoint. This is how you define a reward by matching a specific campaign:

{
  "name":"5$ discount",
  "parameters":{
    "campaign":{
      "id":"camp_gtNM5oQJybruzANwYv1mgHk6"
    }
  }
}

Creating a loyalty campaign

Campaign container

The first step is to define the loyalty program in terms of size and timeframe. To do so, you can use Create Loyalty Program endpoint.

🚧

Time limits

A campaign is only active between the start and end date. You can also use validity timeframes to define the time when points are collected.

{
  "name":"ACME Loyalty Program",
  "start_date":"2018-10-26T00:00:00Z",
  "vouchers_count":1000,
  "voucher":{
    "type":"LOYALTY_CARD",
    "loyalty_card":{
      "points":0
    },
    "code_config":{
      "pattern":"ACME-CARD-#######"
    }
  },
  "metadata":{
    "test":true
  },
  "type":"AUTO-UPDATE"
}

The LOYALTY_CARD voucher type is responsible for creating loyalty cards of the initial number defined with vouchers_count. If type is AUTO-UPDATE, the number will be incremented automatically even if you ran out of the initial pool.
See vouchers to learn more features a loyalty card can carry.

Rewards and their cost in points

Assuming you’ve created at least one coupon/gift card campaign, let’s see how we can include it into your program’s rewards package.

This is a simple process and comes down to creating a Reward Assignment. You need 3 parameters to create one: a campaign id, a reward id, and the number of points that will be deducted from a customer’s account when he or she decides to exchange their points.

https://api.voucherify.io/v1/loyalties/camp_MgpTUyabvEVaGvbUKAOiSVwL/rewards

[
  {
    "reward":"rew_2yGflHThU2yJwFECEFKrXBI2",
    "parameters":{
      "loyalty":{
        "points":15
      }
    }
  }
]

Notes

  • A customer can redeem points only for these rewards which have been linked with the campaign as shown above.
  • All these rewards will show up in a customer’s cockpit.
  • You can add as many rewards as you want.

Adding program participants

Customers can join a program only if you invite them. To do so, you can issue a loyalty card with the Dashboard, or, as usually in Voucherify, use a specific API endpoint.

In this case, you should call Create Member by providing a campaign id and a customer joining the program:

https://api.voucherify.io/v1/loyalties/:campaignId/members

{
  "customer":{
    "source_id":"[email protected]",
    "email":"[email protected]",
    "name":"Test User"
  },
  "metadata":{
    "test":true,
    "provider":"Shop Admin"
  }
}

In response, you'll get a unique loyalty card from the campaign

{
  "id": "v_GqbkSoXI6WDi3WTFJ76xXyrGRSQxYXbD",
  "code": "ACME-CARD-3ug8G2E",
  "campaign": "Loyalty Campaign",
  "campaign_id": "camp_Zgj5HFIPcb70SWJ4IjBNta2F",
  "category": null,
  "type": "LOYALTY_CARD",
  "discount": null,
  "gift": null,
  "loyalty_card": {
    "points": 0,
    "balance": 0
  },
  "start_date": "2016-10-26T00:00:00Z",
  "expiration_date": null,
  "validity_timeframe": null,
  "validity_day_of_week": null,
  "publish": {
    "object": "list",
    "count": 1,
    "url": "/v1/vouchers/ACME-CARD-3ug8G2E/publications?page=1&limit=10"
  },
  "redemption": {
    "object": "list",
    "quantity": null,
    "redeemed_quantity": 0,
    "url": "/v1/vouchers/ACME-CARD-3ug8G2E/redemptions?page=1&limit=10"
  },
  "active": true,
  "additional_info": null,
  "metadata": {
    "test": true
  },
  "is_referral_code": false,
  "holder_id": "cust_ySv6heq8iPQhzt0HjGCFlMni",
  "updated_at": null
}

Alternatively, you can can assign a loyalty card to a customer and invite them to the projects with Create Publication endpoint.

You can List Members to check who’s enrolled at the moment.

Earning points

So, let’s see how you can use the Loyalties API to manager points earning. Having your events set up as shown above, you can start creating earning rules. A typical rules ties an event with a number of points to be earned by a customer.

Sometimes, you might want to impose extra limitation on customers who perform a given event. You can do this by attaching validation rules object to your earning rule.

https://api.voucherify.io/v1/loyalties/camp_Zgj5HFIPcb70SWJ4IjBNta2F/earning-rules

[
  {
    "event":"order.paid",
    "validation_rule_id":null,
    "loyalty":{
      "points":5
    },
    "source":{
      "banner":"Get 5 points for every order!"
    }
  }
]

Redeeming points for rewards

Now that we’ve put together all necessary elements of a loyalty campaign, we can see how to handle points redemption. To do so, just call the Redeem Reward by providing a campaign, participant, and reward id.

https://api.voucherify.io/v1/loyalties/camp_yGEDLqgb9Es1ldwqU3K9PYv0/members/HVqWlozp/redemption
{
  "reward":{
    "id":"rew_2yGflHThU2yJwFECEFKrXBI2"
  },
  "metadata":{
    "locale":"en-GB"
  }
}

Voucherify will calculate if a customer is eligible for redemption, checking both points balance and validation rules (if specified).

In case of success, it creates a redemption object:

{
  "id":"r_sLUnotINY8ML9dfuwlmWm9q9",
  "object":"redemption",
  "date":"2019-04-19T13:17:04Z",
  "customer_id":"cust_PiguvGHitud7xXJ6vHxTCONi",
  "tracking_id":"[email protected]",
  "amount":50,
  "reward":{
    "id":"rew_2yGflHThU2yJwFECEFKrXBI2",
    "assignment_id":"rewa_ilF45izuc5BS1mp6ydyivfXs"
  },
  "metadata":{
    "locale":"en-GB"
  },
  "result":"SUCCESS",
  "voucher":{
    "id":"v_n7ysN4Cs8XPagkulUgtKbNGoZmbbLi5X",
    "code":"HVqWlozp",
    "campaign":"Loyalty program 1",
    "campaign_id":"camp_yGEDLqgb9Es1ldwqU3K9PYv0",
    "category":null,
    "type":"LOYALTY_CARD",
    "discount":null,
    "gift":null,
    "loyalty_card":{
      "points":2000,
      "balance":1950
    },
    "start_date":null,
    "expiration_date":null,
    "validity_timeframe":null,
    "validity_day_of_week":null,
    "publish":{
      "object":"list",
      "count":1,
      "url":"/v1/vouchers/HVqWlozp/publications?page=1&limit=10"
    },
    "redemption":{
      "object":"list",
      "quantity":null,
      "redeemed_quantity":1,
      "url":"/v1/vouchers/HVqWlozp/redemptions?page=1&limit=10",
      "redeemed_points":50
    },
    "active":true,
    "additional_info":null,
    "metadata":null,
    "is_referral_code":false,
    "holder_id":"cust_PiguvGHitud7xXJ6vHxTCONi",
    "updated_at":"2019-04-19T13:17:04Z",
    "object":"voucher"
  }
}

When a customer gains the required amount of points, the reward is automatically published in their cockpit (it's active). Then, they can exchange it for points with a corresponding button.

If the customer chooses to transfer points for the reward, Voucherify updates their points balance.

Maintenance

If you need to set a customer’s balance manually, you can do it with this endpoint

https://api.voucherify.io/v1/loyalties/camp_Zgj5HFIPcb70SWJ4IjBNta2F/members/L-CARD-3ug8G2E/balance

{
  "points": 2000
}

Note that any reward, reward assignment, loyalty campaigns, and its members can be modified via the API. Explore the Rewards and Loyalty APIs to learn the CRUD methods:

Updated 3 months ago

Loyalty program


Suggested Edits are limited on API Reference Pages

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