🚧

Outdated

This document isn't maintained. Please visit the quickstart guide.

Setup

📘

To get started with Voucherify, you need an account. You can get one here (e-mail confirmation required).

Once you confirmed your account:

1. Grab your Application ID and Application Secret Key from the Configuration tab of Voucherify's dashboard.
2. Download and install one of SDKs, available in PHP, Node.js, Ruby, Java, Python, and .NET. Of course, you can interact directly with our REST API too.

If you want to use client-side features of the API for the web or mobile applications, you should use Client Application ID and Client Public Key and one of the client SDKs: Voucherify.js, Android, iOS (Swift). Learn more about Authentication.

Basic concepts

You might want to get familiar with the basic terms like voucher or campaign and overall workflow before you dive into the code. The How it works article is a good place to start. It also shows how developers and marketers interact with respective components of the platform.

Create voucher

What we’re going to create within this tutorial is a standalone, fixed code discount voucher. What does it mean? Imagine the following marketing scenario: you want to give away 50% discount for your products on a day of your product launch.

The code will be promoted through a number of channels to reach out to thousands of people. Additionally, the code should be valid for a specific period. Let’s see how we can model this case with Voucherify. The first step is to create a voucher by invoking this request:

📘

Dashboard mode

There are 2 ways of creating campaigns in Voucherify: programmatically through API and using the dashboard. In this section, we’ll describe the former. If you’re interested in the UI way, go to the How do I create my first campaign? tutorial in the Help Center.

curl -X POST \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
-d '{
    "type": "DISCOUNT_VOUCHER",
    "discount": {
        "percent_off": "50.0",
        "type": "PERCENT"
    },
    "expiration_date": "2020-12-31T23:59:59Z",
    "redemption": {
        "quantity": null
    }
}' "https://api.voucherify.io/v1/vouchers/piedpiper"

The purpose of the request is to create a voucher entity in Voucherify. From now on the code ‘piedpiper’ is recognized as a valid one, meaning every validate call will return true.

Let’s run through the body parameters:

👍

More customization options

The table presents a basic set of voucher parameters. Visit the voucher reference to learn more.

Now, if your request got processed successfully you should see the following response:

{
   "code":"piedpiper",
   "campaign":null,
   "category":null,
   "type":"DISCOUNT_VOUCHER",
   "discount":{
      "type":"PERCENT",
      "percent_off":50.0
   },
   "gift":null,
   "start_date":null,
   "expiration_date":"2020-12-31T23:59:59Z",
   "publish":{
      "object":"list",
      "count":0,
      "url":"/v1/vouchers/piedpiper/publications?page=1&limit=10"
   },
   "redemption":{
      "object":"list",
      "quantity":null,
      "redeemed_quantity":0,
      "url":"/v1/vouchers/piedpiper/redemptions?page=1&limit=10"
   },
   "active":true,
   "additional_info":null,
   "metadata":null,
   "is_referral_code":false,
   "updated_at":null,
   "object":"voucher"
}

(Optional) Client-side validation

To give shoppers better experience, you can enable them to check if the code is correct right in a checkout page, before the order is confirmed.

To do this, you can use our client side SDKs (web, Android and iOS) which do nothing more than invoking validate endpoint. See the demo of voucherify.js

curl -X GET \
-H "X-Client-Application-Id: 011240bf-d5fc-4ef1-9e82-11eb68c43bf5" \
-H "X-Client-Token: 9e2230c5-71fb-460a-91c6-fbee64707a20" \
-H "Content-Type: application/json" \
-H "Origin: origin" \
"https://api.voucherify.io/client/v1/validate?code=piedpiper"

{
   "code":"piedpiper",
   "valid":true,
   "discount":{
      "type":"PERCENT",
      "percent_off":50.0
   },
   "tracking_id":"track_YMLhqKCuxfIEArxcTCZujljAYQUg9fI4nIf/t1mYZ4/9+szePSmClg=="
}

Note: the validate method doesn’t utilize your request quota. It's also worth noting that it’s secured with the IP rate-limiter and domain whitelisting to prevent brute-force attacks.

Redeem integration

Now, when we have the voucher in place, we can distribute it to customers. Voucherify supports this process with many built-in options like email/SMS distribution or CSV export. For the sake of simplicity, let's assume that your voucher code has been pushed out to the market and you have to let customers redeem it at your store. The easiest way to achieve this is to call the Voucherify API in your backend:

curl -X POST \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
-d '{}' "https://api.voucherify.io/v1/vouchers/piedpiper/redemption"

In the case of successful request’s response, you’ll notice that redeemed_quantity has been increased. Voucherify will also pass the discount details, which you can use to modify a price of an order.

{
   "id":"r_Hr6NOkrXjrtkMmzX8ce0hu3F",
   "object":"redemption",
   "date":"2018-01-08T13:10:09Z",
   "customer_id":null,
   "tracking_id":"(tracking_id not set)",
   "result":"SUCCESS",
   "voucher":{
      "code":"piedpiper",
      "campaign":null,
      "category":null,
      "type":"DISCOUNT_VOUCHER",
      "discount":{
         "type":"PERCENT",
         "percent_off":50.0
      },
      "gift":null,
      "start_date":null,
      "expiration_date":"2020-12-31T23:59:59Z",
      "validity_timeframe":null,
      "publish":{
         "object":"list",
         "count":0,
         "url":"/v1/vouchers/piedpiper/publications?page=1&limit=10"
      },
      "redemption":{
         "object":"list",
         "quantity":null,
         "redeemed_quantity":2,
         "url":"/v1/vouchers/piedpiper/redemptions?page=1&limit=10"
      },
      "active":true,
      "additional_info":null,
      "metadata":null,
      "is_referral_code":false,
      "updated_at":"2018-01-08T13:10:09Z",
      "object":"voucher"
   }
}

Monitoring

Congrats! You've just created and redeemed your first voucher. At the end of the day, you might want to summarise the campaign's performance. Let’s assume that you’re interested in how many times your voucher has been redeemed so far. To do so, you should tap into redemption endpoint again:

curl -X GET \
-H "X-App-Id: c70a6f00-cf91-4756-9df5-47628850002b" \
-H "X-App-Token: 3266b9f8-e246-4f79-bdf0-833929b1380c" \
-H "Content-Type: application/json" \
"https://api.voucherify.io/v1/vouchers/piedpiper/redemption"

📘

Failed redemptions

Apart from successful redemption requests, the response will also store entries with failed ones e.g. expired voucher redemptions. Learn more about other failure reasons.

{
   "object":"list",
   "total":2,
   "data_ref":"redemption_entries",
   "quantity":null,
   "redeemed_quantity":2,
   "redemption_entries":[
      {
         "id":"r_Hr6NOkrXjrtkMmzX8ce0hu3F",
         "object":"redemption",
         "date":"2018-01-08T13:10:09.425Z",
         "customer_id":null,
         "tracking_id":null,
         "order":null,
         "metadata":null,
         "result":"SUCCESS",
         "customer":null,
         "related_object_type":"voucher",
         "voucher":{
            "object":"voucher",
            "code":"piedpiper"
         }
      },
      {
         "id":"r_3EUSbh4ahPLl9HdhUp8A9eLq",
         "object":"redemption",
         "date":"2017-09-29T04:58:36.236Z",
         "customer_id":null,
         "tracking_id":null,
         "order":null,
         "metadata":null,
         "result":"SUCCESS",
         "customer":null,
         "related_object_type":"voucher",
         "voucher":{
            "object":"voucher",
            "code":"piedpiper"
         }
      }
   ]
}

You can monitor its performance using the Dashboard too:

Recap

After all, this is how Voucherify integrates into your e-commerce system

Note that this diagram shows a client-side connection too. It's optional. The minimal integration can work with the backend part only.

1. A customer types a code. Your client-side application can validate it.

2. Voucherify responds with the result and discount details in the case of a valid voucher. You can use this information to calculate and show the new price to the customer. From now on, the customer can be tracked with a Voucherify-generated token, read more about client-side customer tracking.

3. Once the customer completes the order, you pass the order details and (optionally) the tracking token to your backend application.

4. Your backend uses an authenticated library to call redeem.

5. Voucherify responds with the redemption details, including redemption status, discount type and a number of redemptions made so far.

📘

Postman collection

You can play around with the endpoints used in the tutorial with Postman

Next steps

You’ve just learned how to wire a fixed-code campaign into your e-commerce system. But Voucherify can do much more than that! Run through examples and user manuals to ensure you get the most out of our API.

Last but not least, you might invite your colleagues and partners to collaborate on campaigns. Read more on user management.

Questions?

We're always happy to help with code or other questions you might have! Search our site for more information or contact us through the live chat.