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

The voucher is an essential resource in Voucherify. Every voucher has a unique code that an end-customer needs to know to make a redemption. Voucherify uses the notion of a voucher to support 3 types of promotions:

πŸ‘

Standalone code

Vouchers can be created as standalone objects e.g., a generally available code "BlackFriday" or as a group of unique codes, see campaigns.

πŸ“˜

Object definition

Voucher object reference

Format

You can define a code pattern using several parameters:

  • charset (alphanumeric, alphabetic lower & uppercase, numbers, custom)
  • length
  • prefix
  • postfix
  • pattern

On top of that Voucherify offers an easy way of generating QR and barcodes. This is simply achieved by placing QR and barcode image links to get voucher response.

{  
  // ...
  "assets":{  
    "qr":{  
      "id":"U2FsdGVkX1+VwsADlREDxcAsQVY7l9Byt6cEX2AKBqJmBZvW0pvxGg1UZlsYikCo9nSxUxNXKQ928Ra0el20OJhqi9XyYo3Rv1KTUabg3fgkCBrrPfQVZsYomE6/Yz/KCxK90Ro3o1Cs4fKDmtnnog==",
      "url":"https://dl.voucherify.io/api/v1/assets/qr/U2FsdGVkX1%2BVwsADlREDxcAsQVY7l9Byt6cEX2AKBqJmBZvW0pvxGg1UZlsYikCo9nSxUxNXKQ928Ra0el20OJhqi9XyYo3Rv1KTUabg3fgkCBrrPfQVZsYomE6%2FYz%2FKCxK90Ro3o1Cs4fKDmtnnog%3D%3D"
    },
    "barcode":{  
      "id":"U2FsdGVkX1+pl1abyxraI3S1WSBmsA+U6tkJiTXlEdCBitA9D4W5R46rkMvirKA3CE0tYcSdAgOxQQYD6z8fvs7aG6NSVeq5K7rhNvrGXP+OO+yfA03tgBNcVU89vhu8iyhI58NmzciUIZSfEPdy3w==",
      "url":"https://dl.voucherify.io/api/v1/assets/barcode/U2FsdGVkX1%2Bpl1abyxraI3S1WSBmsA%2BU6tkJiTXlEdCBitA9D4W5R46rkMvirKA3CE0tYcSdAgOxQQYD6z8fvs7aG6NSVeq5K7rhNvrGXP%2BOO%2ByfA03tgBNcVU89vhu8iyhI58NmzciUIZSfEPdy3w%3D%3D"
    }
  }
}

πŸ‘

Configure size and format of QR

You can change a size or/and a format of the file by using these query string params:

  • size (integer) - value from 1 to 100 (default 10)
  • format (string) - png (default) or svg

πŸ‘

Configure size and format of barcode

You can change a size of the file by using this query string param:

  • size (integer) - value from 1 to 100 (default 20)

Vouchers maintenance

The Voucherify dashboard gives marketers control over every single voucher code. They can modify the parameters and state of any code at any time. But if you need to run a bulk operations on several vouchers, these API endpoints might be useful:

Read more about importing codes.

Discount coupons

A discount coupon represents one of 3 discount types:

  • amount ($10 off)
  • percentage (20% off)
  • unit (2 piano lessons)

πŸ‘

Upper limit

For the percentage type, you can also set the upper dollar value of a discount. You can run a "10% off campaign" and set the upper value of a discount equal to $100. It means that every customer with a code get max. $100 discount even if their order will be worth more than $1000 (orders above $1000 get less than 10% discount).

Gift cards

Apart from discount coupons, Voucherify can process gift cards. Similarly to the discount coupon, the gift card is assigned a value e.g. $100. The difference, however, lies in the redemption step. A discount redemption is a one-off action whereas the gift card enables partial redemption. So until the customer has the balance her gift card can still be used. Let's see how to achieve this programmatically.

πŸ“˜

Dashboard mode

This tutorial presents how to achieve this in the UI

In case you want to create this campaign with the API, it boils down to calling campaigns endpoint with the following payload:

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 '{
    "name": "Gift cards October",
    "vouchers_count": 50,
    "voucher": {
        "type": "GIFT_VOUCHER",
        "gift": {
            "amount": 10000
        },
        "redemption": {
          "quantity": null
        }
    }
}' "https://api.voucherify.io/v1/campaigns"
{  
  "name":"Gift cards October",
  "type":"STATIC",
  "description":null,
  "start_date":null,
  "expiration_date":null,
  "metadata":null,
  "vouchers_count":50,
  "vouchers_generation_status":"IN_PROGRESS",
  "voucher":{  
    "code_config":{  
      "length":8,
      "charset":"0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ",
      "pattern":"########"
    },
    "type":"GIFT_VOUCHER",
    "is_referral_code":false,
    "gift":{  
      "amount":10000,
      "balance":10000
    },
    "redemption":{  
      "quantity":null
    }
  },
  "object":"campaign"
}

Redemption

To redeem the gift card voucher you should call redeem request providing the amount to be spent. In the following example, we decrease the balance by $50 (note: Voucherify processes decimals by multiplying all amounts by 100).

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 '{
    "order": {
      "amount": 5000
    }
}
' "https://api.voucherify.io/v1/vouchers/h73YQbhR/redemption"
{  
  "id":"r_J24B5tnDyUbfwEEO5T0Dbhf7",
  "object":"redemption",
  "date":"2017-05-19T09:25:39Z",
  "customer_id":null,
  "tracking_id":"(tracking_id not set)",
  "amount":5000,
  "order":{  
    "object":"order",
    "id":"ord_8prx3NzPrN5GSKWjS6IrePg2",
    "source_id":null,
    "amount":5000,
    "created_at":"2017-05-19T09:25:39Z",
    "updated_at":null,
    "items":null,
    "customer":null,
    "status":"CREATED",
    "metadata":null
  },
  "result":"SUCCESS",
  "voucher":{  
    "code":"h73YQbhR",
    "campaign":"Gift cards October",
    "category":null,
    "type":"GIFT_VOUCHER",
    "discount":null,
    "gift":{  
      "amount":10000,
      "balance":5000
    },
    "start_date":null,
    "expiration_date":null,
    "publish":{  
      "object":"list",
      "count":0,
      "url":"/v1/vouchers/h73YQbhR/publications?page=1&limit=10"
    },
    "redemption":{  
      "object":"list",
      "quantity":null,
      "redeemed_quantity":1,
      "redeemed_amount":5000,
      "url":"/v1/vouchers/h73YQbhR/redemptions?page=1&limit=10"
    },
    "active":true,
    "additional_info":null,
    "metadata":null,
    "is_referral_code":false,
    "updated_at":"2017-05-19T09:25:39Z"
  }
}

And if we try spending more than the current balance allows for Voucherify returns error message:

{  
  "code":400,
  "message":"gift amount exceeded",
  "details":"h73YQbhR",
  "key":"gift_amount_exceeded"
}

The voucher can be redeemed using Dashboard as well. Just go to the voucher details view, press REDEEM and provide the amount in the following popup.

Recharge

Supposing you want to recharge the cards you've sent out to your customers. With our API you can edit the balance value by calling Add Balance endpoint. From now on, the voucher can be redeemed again.

Export

Vouchers (along with redemptions, publications, and customers) can be downloaded asynchronously with the export mechanism, see the docs.

Voucher attributes you can export: code, voucher_type, value, discount_type, campaign, category, start_date, expiration_date, gift_balance, redemption_quantity, active, qr_code

Updated about a year ago

Vouchers


Suggested Edits are limited on API Reference Pages

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