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

Publish channels

Sometimes you're interested in storing the information about how a particular coupon has been delivered to customers. E.g. you want to keep a record of whether codes from the piedpiper campaign have been exported to CSV or sent via email. Our API has an endpoint which helps you out - meet the publish endpoint.

Publication

To track voucher publications, you should ensure that the publish method is invoked. This can be achieved with multiple ways in Voucherify and each one covers different scenario. We have 2 types:

  • programmable - explicit call of the publish endpoint (ability to provide a custom channel)
  • automatic - invoked automatically every time a voucher is exported to a CSV file or when a distribution is run.

Programmable publication

Let's imagine 2 situations:

  • you want to publish a specific code to a specific customer
  • you want to publish any code from a given campaign and then make sure that the same code won't be published ever again.

Handling both of these scenarios comes down to calling the publish method in a slightly different way.

Specific voucher code

In the following example, we publish BmkocdXu code to the specific customer (cust_hOA02xicf72GZYsYko4y1CMc). As you can see, we defined a channel which is an optional parameter but can be used for reporting in the future.

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 '{
      "voucher": "ycs2AnLT",
        "customer": "cust_RZa0oS7qUT9giVISFVJhKlMq",
        "channel": "newsletter_October"
    }' \
    https://api.voucherify.io/v1/publications

This creates the following publication object

{
   "id":"pub_r5jzJLCnKW3JIKrMcGsZhjmf",
   "object":"publication",
   "created_at":"2018-07-31T12:10:40Z",
   "customer_id":"cust_RZa0oS7qUT9giVISFVJhKlMq",
   "tracking_id":"12344",
   "channel":"newsletter_October",
   "voucher":{
      "code":"ycs2AnLT",
      "campaign":null,
      "category":null,
      "type":"DISCOUNT_VOUCHER",
      "discount":{
         "type":"PERCENT",
         "percent_off":10.0
      },
      "gift":null,
      "start_date":null,
      "expiration_date":null,
      "validity_timeframe":null,
      "validity_day_of_week":null,
      "publish":{
         "object":"list",
         "count":1,
         "url":"/v1/vouchers/ycs2AnLT/publications?page=1&limit=10"
      },
      "redemption":{
         "object":"list",
         "quantity":1,
         "redeemed_quantity":0,
         "url":"/v1/vouchers/ycs2AnLT/redemptions?page=1&limit=10"
      },
      "active":true,
      "additional_info":null,
      "metadata":null,
      "is_referral_code":false,
      "updated_at":"2018-07-31T12:10:40Z"
   }
}

Dynamic code

So, now imagine you want to publish a code from a predefined pool (campaign). You don't care about which code is delivered to a customer unless it's unique. E.g., you want to send coupons to first 1000 users who sign up for a newsletter.

The first thing is to create a respective campaign with 1000 codes. Once you do it, you can start use the publish method. This time you pass the campaign name and provide a customer profile:

📘

Auto-update option

In case you don't know the amount of codes to be published, the AUTO-UPDATE campaign might be helpful. Such a campaign will be auto-extended with a new, unique code after an original pool of codes has been used.

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 '{
    "campaign": { 
      "name": "100k-test", 
      "count": 2 
    },
        "customer": {
      "email": "[email protected]",
      "name": "Erlich Bachman"
    },
    "metadata": {
      "test": true,
      "provider": "Shop Admin"
    }
  }' \
  https://api.voucherify.io/v1/publications

Note: in the previous example, we assigned the publication to an existing customer (identified with the cust_id), in this case we're using customer section to create a new customer entity.

{
   "id":"pub_b03zI1AVaBHjDl4QSjs3Drve",
   "object":"publication",
   "created_at":"2018-07-31T12:12:52Z",
   "customer_id":"cust_lDnTN0zZfoXJDdgZRV0DzDP6",
   "channel":"API",
   "metadata":{
      "test":true,
      "provider":"Shop Admin"
   },
   "vouchers":[
      "pNAtHYW8",
      "8tOtXQQa"
   ]
}

Automatic publication

Every time a coupon code is published either from a distribution or a referral campaign, Voucherify stores a corresponding publication entry. When you get the voucher, its publish section of the response body will show the publication details, e.g.:

publish":{  
      "object":"list",
      "count":1,
      "data_ref":"entries",
      "entries":[  
         {  
            "customer_id":"cust_RZa0oS7qUT9giVISFVJhKlMq",
            "customer":"12344",
            "channel":"newsletter_October",
            "published_at":"2018-07-31T12:10:41Z",
            "metadata":null,
            "object":"publication"
         }
      ],
      "total":1,
      "url":"/v1/vouchers/ycs2AnLT/publications?page=1&limit=10"
   }

This table lists built-in publication channels

Channel

Record

Manual distribution

Dashboard

Automatic distribution

Automation

Referral program

Automation

Explicit create publication call

API (default, can be modified)

Publication history

Want to list recent publications in the Dashboard? No problem, the PUBLICATION HISTORY section in the campaign view makes it possible:

all published codes from a campaign

Updated about a year ago

Publish channels


Suggested Edits are limited on API Reference Pages

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