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 | Orders | Loyalties | Rewards | 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 Endpoint

Optionally, you can add apiUrl to the client options if you want to use Voucherify running in a specific region.

voucherify = Voucherify::Client.new({
  :applicationId => 'YOUR-APPLICATION-ID',
  :clientSecretKey => 'YOUR-CLIENT-SECRET-KEY',
  :apiUrl => 'https://<region>.api.voucherify.io'
})

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)

List Publications

voucherify.distributions.list_publications(params)

Create Publication

voucherify.distributions.create_publication(publication)

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);

List Validation Rules

voucherify.validation_rules.list(query);

Update Validation Rules

voucherify.validation_rules.update(rules);

Delete Validation Rules

voucherify.validation_rules.delete(id);

Create Validation Rule Assignment

voucherify.validation_rules.assignments.create(rule_id, assignment);

List Validation Rule Assignments

voucherify.validation_rules.assignments.list(rule_id, query);

Delete Validation Rule Assignment

voucherify.validation_rules.assignments.delete(rule_id, assignment_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);

Orders API

Create Order

voucherify.orders.create(order);

Get Order

voucherify.orders.get(id);

Update Order

voucherify.orders.update(id, order);

List orders

voucherify.orders.list(params);

Rewards API

Create Rewards

voucherify.rewards.create(reward);

Get Reward

voucherify.rewards.get(id);

Update Reward

voucherify.rewards.update(id, reward);

List Rewards

voucherify.rewards.list(params);

Delete Reward

voucherify.rewards.delete(id);

List Reward Assignments

voucherify.rewards.assignments.list(reward_id, query);

Create Reward Assignment

voucherify.rewards.assignments.create(reward_id, assignment);

Update Reward Assignment

voucherify.rewards.assignments.update(reward_id, assignment_id, assignment);

Delete Reward Assignment

voucherify.rewards.assignments.delete(reward_id, assignment_id);

Loyalties API

List Loyalties

voucherify.loyalties.list(query);

Create Loyalty

voucherify.loyalties.create(loyalty);

Get Loyalty

voucherify.loyalties.get(id);

Update Loyalty

voucherify.loyalties.update(id, loyalty);

Delete Loyalty

voucherify.loyalties.delete(id);

List Loyalty Reward Assignments

voucherify.loyalties.assignments.list(loyalty_id, query);

Create Loyalty Reward Assignment

voucherify.loyalties.assignments.create(loyalty_id, assignment);

Update Loyalty Reward Assignment

voucherify.loyalties.assignments.update(loyalty_id, assignment_id, assignment);

Delete Loyalty Reward Assignment

voucherify.loyalties.assignments.delete(loyalty_id, assignment_id);

List Loyalty Earning Rules

voucherify.loyalties.earning_rules.list(loyalty_id, query);

Create Loyalty Earning Rule

voucherify.loyalties.earning_rules.create(loyalty_id, earning_rule);

Update Loyalty Earning Rule

voucherify.loyalties.earning_rules.update(loyalty_id, earning_rule_id, earning_rule);

Delete Loyalty Earning Rule

voucherify.loyalties.earning_rules.delete(loyalty_id, earning_rule_id);

List Loyalty Members

voucherify.loyalties.members.list(loyalty_id, query);

Add Loyalty Member

voucherify.loyalties.members.add(loyalty_id, member);

Get Loyalty Member

voucherify.loyalties.members.get(loyalty_id, member_id);

Add Loyalty Card Balance

voucherify.loyalties.members.add_balance(loyalty_id, member_id, add_balance);

Redeem Loyalty Reward

voucherify.loyalties.members.redeem_reward(loyalty_id, member_id, redeem_reward);

Events API

Methods are provided within voucherify.events.* namespace.

Create event

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

voucherify.events.track_event(data);

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

  • 2019-06-19 - 2.4.0 - Added support for custom API endpoint, that allows to connect to projects created in specific Voucherify region.
  • 2019-05-09 - 2.3.0 - Added create_publication method in Distributions module..
  • 2019-04-23 - 2.2.0 - Loyalties API, Rewards API, Orders API.
  • 2019-02-19 - 2.1.1 - Treat referral as optional in custom events. Added new method for custom event tracking.
  • 2019-02-19 - 2.1.0 - Handle referral in custom events tracking.
  • 2018-12-27 - 2.0.0 - Business validation rules.
  • 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.