Ruby SDK for Voucherify - coupons, vouchers, promo codes
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
examples
lib
spec
.gitignore
.rspec
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
voucherify-ruby-sdk.png
voucherify.gemspec

README.md

Official Voucherify SDK for Ruby

Build Status Gem Version Gem Downloads


Migration from 0.x | Setup | Error handling | Development | Contributing | Changelog

API: Vouchers | Campaigns | Distributions | Validations | Redemptions | Customers | Products | Validation Rules | Segments | Promotions | Events | Utils


Setup

Add this line to your application's Gemfile:

gem 'voucherify'

And then execute:

$ bundle

Or install it yourself as:

$ gem install voucherify

Log-in to Voucherify web interface and obtain your Application Keys from Configuration:

require 'voucherify'

voucherify = Voucherify::Client.new({
  :applicationId => 'YOUR-APPLICATION-ID',
  :clientSecretKey => 'YOUR-CLIENT-SECRET-KEY'
})

You can also specify which API version you want to use:

voucherify = Voucherify::Client.new({
  :applicationId => 'YOUR-APPLICATION-ID',
  :clientSecretKey => 'YOUR-CLIENT-SECRET-KEY',
  :apiVersion => 'v2017-04-05'
})

and timeout settings:

voucherify = Voucherify::Client.new({
  :applicationId => 'YOUR-APPLICATION-ID',
  :clientSecretKey => 'YOUR-CLIENT-SECRET-KEY',
  :apiVersion => 'v2017-04-05',
  :timeout => 10 // in seconds
})

API

This SDK is fully consistent with restful API Voucherify provides. Detailed descriptions and example responses you will find at official docs. Method headers point to more detailed params description you can use.

Vouchers API

Methods are provided within voucherify.vouchers.* namespace.

Create Voucher

voucherify.vouchers.create(code, options)

Check voucher object.

Get Voucher

voucherify.vouchers.get(code)

Update Voucher

voucherify.vouchers.update(voucher)

Delete Voucher

voucherify.vouchers.delete(code, [params])

List Vouchers

voucherify.vouchers.list

Enable Voucher

voucherify.vouchers.enable(code)

Disable Voucher

voucherify.vouchers.disable(code)

Import Vouchers

voucherify.vouchers.import(vouchers)

Add Gift Voucher Balance

voucherify.vouchers().add_balance(code, balance);

Campaigns API

Methods are provided within voucherify.campaigns.* namespace.

Create Campaign

voucherify.campaigns.create(campaign)

Get Campaign

voucherify.campaigns.get(campaign_name)

Add Voucher to Campaign

voucherify.campaigns.add_voucher(campaign_name, [params])

Import Vouchers to Campaign

voucherify.campaigns.import_vouchers(campaign_name, vouchers)

Distributions API

Methods are provided within voucherify.distributions.* namespace.

Publish Vouchers

voucherify.distributions.publish(campaign_name)

Create Export

voucherify.distributions.create_export(export)

Get Export

voucherify.distributions.get_export(export_id)

Delete Export

voucherify.distributions.delete_export(export_id)

Validations API

Methods are provided within voucherify.validations.* namespace.

Validate Voucher

voucherify.validations.validate_voucher(code, [context])

# or

voucherify.validations.validate(code, [context])

Validate Promotion Campaign

voucherify.validations.validate(promo_validation_context)

Redemptions API

Methods are provided within voucherify.redemptions.* namespace.

Redeem Voucher

# Redeem voucher code
voucherify.redemptions.redeem(code, [params])

# Redeem promotion campaign
voucherify.redemptions.redeem(promotions_tier, [params])

# Removed!
voucherify.redemptions.redeem(code, tracking_id) # use: voucherify.redemptions.redeem(code, {:customer => {:source_id => 'source_id'}})

List Redemptions

voucherify.redemptions.list
voucherify.redemptions.list(params)

Get Voucher's Redemptions

voucherify.redemptions.get_for_voucher(code)

Get Redemption

voucherify.redemptions.get(redemption_id);

Rollback Redemption

voucherify.redemptions.rollback(redemption_id, [params])

# Removed!
voucherify.redemptions.rollback(code, tracking_id, reason) # use: voucherify.redemptions.rollback(code, {:customer => {:source_id => 'source_id'}, :reason => 'reason'})

Check redemption rollback object.


Promotions API

Methods are provided within voucherify.promotions.* namespace.

Check promotion campaign object.

Create Promotion Campaign

voucherify.promotions.create(promotion_campaign)

Validate Promotion Campaign

voucherify.promotions.validate(validation_context)

List Promotion's Tiers

voucherify.promotions.tiers.list(promotion_campaign_id)

Check promotion's tier object

Create Promotion's Tier

voucherify.promotions.tiers.create(promotion_id, promotions_tier)

Redeem Promotion's Tier

voucherify.promotions.tiers.redeem(promotions_tier_id, redemption_context)

Update Promotion's Tier

voucherify.promotions.tiers.update(promotions_tier)

Delete Promotion's Tier

voucherify.promotions.tiers.delete(promotions_tier_id)

Customers API

Methods are provided within voucherify.customers.* namespace.

Create Customer

voucherify.customers.create(customer)

Check customer object.

Get Customer

voucherify.customers.get(customer_id)

Update Customer

voucherify.customers.update(customer)

Delete Customer

voucherify.customers.delete(customer_id)

Products API

Methods are provided within voucherify.products.* namespace.

Create Product

voucherify.products.create(product)

Check product object.

Get Product

voucherify.products.get(product_id)

Update Product

voucherify.products.update(product)

Delete Product

voucherify.products.delete(product_id)

List Products

voucherify.products.list([params])

Create SKU

voucherify.products.create_sku(product_id, sku)

Check SKU object.

Get SKU

voucherify.products.get_sku(product_id, sku_id)

Update SKU

voucherify.products.update_sku(product_id, sku)

Delete SKU

voucherify.products.delete_sku(product_id, sku_id)

List all product SKUs

voucherify.products.list_skus(product_id)

Validation Rules API

Methods are provided within voucherify.validation_rules.* namespace.

Create Validation Rules

voucherify.validation_rules.create(rules);

Get Validation Rules

voucherify.validation_rules.get(id);

Update Validation Rules

voucherify.validation_rules.update(rules);

Delete Validation Rules

voucherify.validation_rules.delete(id);

Segments API

Methods are provided within voucherify.segments.* namespace.

Create Segment

voucherify.segments.create(segment);

Get Segment

voucherify.segments.get(id);

Delete Segment

voucherify.segments.delete(id);

Events API

Methods are provided within voucherify.events.* namespace.

[Create event]

voucherify.events.track(event, metadata, customer);

Migration from 0.x

Version 1.x of the SDK is not backwards compatible with versions 0.x. Changes made in version 1.x mostly relate to grouping methods within namespaces. So all you need to do is to follow the list bellow and just replace methods with their namespaced equivalent.


Utils

Available methods

  • Voucherify::Utils.round_money(value)
  • Voucherify::Utils.validate_percent_discount(discount)
  • Voucherify::Utils.validate_amount_discount(discount)
  • Voucherify::Utils.validate_unit_discount(discount)
  • Voucherify::Utils.calculate_price(base_price, voucher, [unit_price])
  • Voucherify::Utils.calculate_discount(base_price, voucher, [unit_price])

Error handling

When the Voucherify API responds with an error (HTTP status code is 4xx or 5xx) then the client raises a VoucherifyError. It contains following properties:

  • code - HTTP status code
  • message - a human-readable message providing short description about the error.
  • details - a human-readable message providing more details about the error, usually includes a hint on how to fix the error
  • key - a short string describing the kind of error that occurred.

Example:

begin
  voucherify.distributions.publish('test')
rescue Voucherify::VoucherifyError => e
  puts e.code
  puts e.message
  puts e.details
  puts e.key
end

The ouput may be:

400
Couldn't find any voucher suitable for publication.
Use auto-update campaigns if you want Voucherify to generate vouchers automatically.
no_voucher_suitable_for_publication

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

  • 2018-09-05 - 1.6.1 - Request timeout settings
  • 2017-11-16 - 1.6.0 - Expose promotion API, Redemptions and Validations namespace update
  • 2017-11-16 - 1.5.0 - Expose events API
  • 2017-05-07 - 1.4.0 - Segments, Validation rules, API Versioning
  • 2017-03-22 - 1.3.0 - improved error handling
  • 2017-01-04 - 1.2.0 - added import vouchers method.
  • 2016-12-29 - 1.1.0 - introduced campaigns api and products api.
  • 2016-12-15 - 1.0.0 - introduced namespaces, unified method names, updated README. Migration from versions 0.x required migration from version 0.x
  • 2016-12-02 - 0.8.2 - support gift vouchers in utils, fix price and discount calculations for amount discounts
  • 2016-10-03 - 0.8.1 - publish update
  • 2016-08-02 - 0.8.0 - validate voucher
  • 2016-07-18 - 0.7.0 - voucher udpate
  • 2016-07-05 - 0.6.0 - new utils module
  • 2016-06-16 - 0.5.0 - unified naming convention
  • 2016-06-12 - 0.4.0 - new customer sdk methods
  • 2016-05-24 - 0.3.0 - new publish structure
  • 2016-04-27 - 0.2.0 - rollback redemption
  • 2016-04-13 - 0.1.3 - bugfix in redeem()
  • 2016-04-13 - 0.1.2 - removed dependency to pry
  • 2016-04-12 - 0.1.1 - minor gemspec changes
  • 2016-04-12 - 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.