Voucherify Ruby SDK
Voucherify has a new platform that will help your team automate voucher campaigns. It does this by providing composable API and the marketer-friendly interface that increases teams' productivity:
- roll-out thousands of vouchers in minutes instead of weeks,
- check status or disable every single promo code in real time,
- track redemption history and build reports on the fly.
Here you can find a library that makes it easier to integrate Voucherify with your Ruby server.
Full documentation is located at voucherify.readme.io.
Usage
Installation
Add this line to your application's Gemfile:
gem 'voucherify'
And then execute:
$ bundle
Or install it yourself as:
$ gem install voucherify
Authentication
Log-in to Voucherify web interface and obtain your Application Keys from Configuration:
require "voucherify"
voucherify = Voucherify.new({
"applicationId" => "YOUR-APPLICATION-ID-OBTAINED-FROM-CONFIGURATION",
"clientSecretKey" => "YOUR-CLIENT-SECRET-KEY-OBTAINED-FROM-CONFIGURATION"
})
Error handling
This voucherify gem uses rest-client under the hood for handling HTTP calls. In case of an HTTP 4xx or 5xx error, a RestClient exception is thrown. The server's specific response is available in .response of the exception object.
begin
voucherify.publish("test")
rescue => e
JSON.parse(e.response)
end
{
"code": 400,
"message": "Couldn't find any voucher suitable for publication."
}
Please refer to rest-client documentation for more detailed information.
Listing vouchers
voucherify.list({ limit: 10, skip: 20, category: "API Test" })
Result:
[{
"code": "9mYBpIk",
"campaign": null,
"category": "API Test",
"discount": {
"type": "AMOUNT",
"amount_off": 400
},
"start_date": "2016-03-01T12:00:00Z",
"expiration_date": null,
"redemption": {
"quantity": 1,
"redeemed_quantity": 0,
"redemption_entries": []
},
"active": true,
"additional_info": null,
"metadata": null
},
{
"code": "AzTsIH",
"campaign": null,
"category": "API Test",
"discount": {
"type": "AMOUNT",
"amount_off": 400
},
"start_date": "2016-03-01T10:00:00Z",
"expiration_date": null,
"redemption": {
"quantity": 1,
"redeemed_quantity": 0,
"redemption_entries": []
},
"active": true,
"additional_info": null,
"metadata": null
},
...
]
Getting voucher details
voucherify.get("v1GiJYuuS")
Result:
{
"code": "v1GiJYuuS",
"campaign": "vip",
"discount": {
"percent_off": 10.0,
"type": "PERCENT"
},
"expiration_date": "2015-12-31T23:59:59Z",
"redemption": {
"quantity": 3,
"redeemed_quantity": 1,
"redemption_entries": [
{
"date": "2015-09-24T06:03:35Z",
"tracking_id": "GENERATED-OR-PROVIDED-TRACKING-ID"
}
]
},
"additional_info": ""
}
Getting voucher redemption
voucherify.redemption("v1GiJYuuS")
Result:
{
"quantity": 3,
"redeemed_quantity": 1,
"redemption_entries": [
{
"date": "2015-09-24T06:03:35Z",
"tracking_id": "GENERATED-OR-PROVIDED-TRACKING-ID"
}
]
}
Publishing voucher
This method selects active, unpublished voucher from the specific campaign and returns it to client. In effect, this voucher is marked as published and it will not be announced once again to customer.
Example:
voucherify.publish("First Ride")
Positive result:
{
"code": "FR-zT-u9I7zG",
"campaign": "First Ride",
"category": null,
"discount": {
"type": "PERCENT",
"amount_off": 50
},
"start_date": "2015-01-01T00:00:00Z",
"expiration_date": "2016-12-31T23:59:59Z",
"redemption": {
"quantity": 1,
"redeemed_quantity": 0,
"redemption_entries": []
},
"active": true,
"additional_info": null,
"metadata": {
"published": "2016-01-22T09:25:07Z"
}
}
Possible error:
{
"code": 400,
"message": "Couldn't find any voucher suitable for publication."
}
Redeeming voucher
1. Just by code
voucherify.redeem("v1GiJYuuS")
Result (voucher details after redemption):
{
"code": "v1GiJYuuS",
"campaign": "vip",
"discount": {
"percent_off": 10.0,
"type": "PERCENT"
},
"expiration_date": "2015-12-31T23:59:59Z",
"redemption": {
"quantity": 3,
"redeemed_quantity": 2,
"redemption_entries": [
{
"date": "2015-09-24T06:03:35Z",
"tracking_id": "(tracking_id not set)"
},
{
"date": "2015-09-25T10:34:57Z",
"tracking_id": "(tracking_id not set)"
},
]
},
"additional_info": ""
}
Error:
{
"code": 400,
"message": "voucher expired or quantity exceeded",
"details": "v1GiJYuuS"
}
2. With tracking id
You can provide a tracking id (e.g. your customer's login or a generated id) to the voucher redemption request.
voucherify.redeem("v1GiJYuuS", "alice.morgan")
Result:
{
"code": "v1GiJYuuS",
"campaign": "vip",
"discount": {
"percent_off": 10.0,
"type": "PERCENT"
},
"expiration_date": "2015-12-31T23:59:59Z",
"redemption": {
"quantity": 3,
"redeemed_quantity": 3,
"redemption_entries": [
{
"date": "2015-09-24T06:03:35Z",
"tracking_id": "(tracking_id not set)"
},
{
"date": "2015-09-25T10:34:57Z",
"tracking_id": "(tracking_id not set)"
},
{
"date": "2015-09-25T12:04:08Z",
"tracking_id": "alice.morgan"
},
]
},
"additional_info": ""
}
3. With customer profile
You can record a detailed customer profile consisting of an id (obligatory), name, email, description and a metadata section that can include any data you wish.
voucherify.redeem({
voucher: "v1GiJYuuS",
customer: {
id: "alice.morgan",
name: "Alice Morgan",
email: "[email protected]",
description: "",
metadata: {
locale: "en-GB",
shoeSize: 5,
favourite_brands: ["Armani", "L’Autre Chose", "Voucherify"]
}
})
Listing redemptions
Use voucherify.redemptions(filter) to get a filtered list of redemptions.
Example - 1000 successful redemptions from April 2016:
filter = {
limit: 1000,
page: 0,
start_date: "2016-04-01T00:00:00",
end_date: "2016-04-30T23:59:59",
result: "Success"
}
voucherify.redemptions(filter)
Creating vouchers
Use voucherify.create(code, options) to create new vouchers.
code = "EASTER-2016" # use given voucher code
code = nil # for an automatically generated string
# single-use voucher with 10% off discount that is valid throughout the whole 2016
opts = {
category: "New Customers",
discount: {
percent_off: 10.0,
type: "PERCENT"
},
start_date: "2016-01-01T00:00:00Z",
expiration_date: "2016-12-31T23:59:59Z",
redemption: {
quantity: 1
}
}
voucherify.create(code, opts)
Result (voucher details):
{
"code": "9Yi5g",
"campaign": null,
"category": "New Customers",
"discount": {
"type": "PERCENT",
"percent_off": 10.0
},
"start_date": "2016-01-01T00:00:00Z",
"expiration_date": "2016-12-31T23:59:59Z",
"redemption": {
"quantity": 1,
"redeemed_quantity": 0,
"redemption_entries": []
},
"active": true,
"additional_info": null,
"metadata": null
}
Disable a voucher
voucherify.disable("EASTER-2016")
The response has empty body.
Enable a voucher
voucherify.enable("EASTER-2016")
The response has empty body.
Development
After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/rspective/voucherify-ruby-sdk.
Changelog
- 2016-04-11 -
0.1.0- First version:- Authentication
- Voucher information: retrieve voucher, list vouchers, retrieve redemptions, list redemptions
- Voucher operations: redeem voucher, publish voucher, create voucher, enable/disable voucher
License
The gem is available as open source under the terms of the MIT License.