This repository is no longer actively maintained, we have a new SDK for Ruby at voucherifyio/sdk-ruby-openapi-based.

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

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

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'
})

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.

Methods are provided within voucherify.vouchers.* namespace.

• Create Voucher
• Get Voucher
• Update Voucher
• Delete Voucher
• List Vouchers
• Enable Voucher
• Disable Voucher
• Import Vouchers
• Add Gift Voucher Balance

voucherify.vouchers.create(code, options)

Check voucher object.

voucherify.vouchers.get(code)

voucherify.vouchers.update(voucher)

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

voucherify.vouchers.list

voucherify.vouchers.enable(code)

voucherify.vouchers.disable(code)

voucherify.vouchers.import(vouchers)

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

Methods are provided within voucherify.campaigns.* namespace.

• Create Campaign
• Get Campaign
• Add Voucher to Campaign
• Import Vouchers to Campaign

voucherify.campaigns.create(campaign)

voucherify.campaigns.get(campaign_name)

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

voucherify.campaigns.import_vouchers(campaign_name, vouchers)

Methods are provided within voucherify.distributions.* namespace.

• Publish Vouchers
• Create Export
• Get Export
• Delete Export
• List Publications
• Create Publication

voucherify.distributions.publish(campaign_name)

voucherify.distributions.create_export(export)

voucherify.distributions.get_export(export_id)

voucherify.distributions.delete_export(export_id)

voucherify.distributions.list_publications(params)

voucherify.distributions.create_publication(publication)

Methods are provided within voucherify.validations.* namespace.

• Validate Voucher
• Validate Promotion Campaign

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

# or

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

voucherify.validations.validate(promo_validation_context)

Methods are provided within voucherify.redemptions.* namespace.

• Redeem Voucher
• List Redemptions
• Get Voucher's Redemptions
• Get Redemption
• Rollback Redemption

# 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'}})

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

voucherify.redemptions.get_for_voucher(code)

voucherify.redemptions.get(redemption_id);

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.

Methods are provided within voucherify.promotions.* namespace.

• Create Promotion Campaign
• Validate Promotion Campaign
• List Promotion's Tiers
• Create Promotion's Tier
• Redeem Promotion's Tier
• Update Promotion's Tier
• Delete Promotion's Tier

Check promotion campaign object.

voucherify.promotions.create(promotion_campaign)

voucherify.promotions.validate(validation_context)

voucherify.promotions.tiers.list(promotion_campaign_id)

Check promotion's tier object

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

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

voucherify.promotions.tiers.update(promotions_tier)

voucherify.promotions.tiers.delete(promotions_tier_id)

Methods are provided within voucherify.customers.* namespace.

• List Customers
• Create Customer
• Get Customer
• Update Customer
• Delete Customer

voucherify.customers.list(options)

Check options.

voucherify.customers.create(customer)

Check customer object.

voucherify.customers.get(customer_id)

voucherify.customers.update(customer)

voucherify.customers.delete(customer_id)

Methods are provided within voucherify.products.* namespace.

• Create Product
• Get Product
• Update Product
• Delete Product
• List Products
• Create SKU
• Get SKU
• Update SKU
• Delete SKU
• List all product SKUs

voucherify.products.create(product)

Check product object.

voucherify.products.get(product_id)

voucherify.products.update(product)

voucherify.products.delete(product_id)

voucherify.products.list([params])

voucherify.products.create_sku(product_id, sku)

Check SKU object.

voucherify.products.get_sku(product_id, sku_id)

voucherify.products.update_sku(product_id, sku)

voucherify.products.delete_sku(product_id, sku_id)

voucherify.products.list_skus(product_id)

Methods are provided within voucherify.validation_rules.* namespace.

• Create Validation Rules

• Get Validation Rules

• List Validation Rules

• Update Validation Rules

• Delete Validation Rules

• Create Validation Rule Assignment

• List Validation Rule Assignments

• Delete Validation Rule Assignment

voucherify.validation_rules.create(rules);

voucherify.validation_rules.get(id);

voucherify.validation_rules.list(query);

voucherify.validation_rules.update(rules);

voucherify.validation_rules.delete(id);

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

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

voucherify.validation_rules.assignments.delete(rule_id, assignment_id);

Methods are provided within voucherify.segments.* namespace.

• Create Segment
• Get Segment
• Delete Validation Rules

voucherify.segments.create(segment);

voucherify.segments.get(id);

voucherify.segments.delete(id);

voucherify.orders.create(order);

voucherify.orders.get(id);

voucherify.orders.update(id, order);

voucherify.orders.list(params);

voucherify.rewards.create(reward);

voucherify.rewards.get(id);

voucherify.rewards.update(id, reward);

voucherify.rewards.list(params);

voucherify.rewards.delete(id);

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

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

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

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

voucherify.loyalties.list(query);

voucherify.loyalties.create(loyalty);

voucherify.loyalties.get(id);

voucherify.loyalties.update(id, loyalty);

voucherify.loyalties.delete(id);

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

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

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

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

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

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

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

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

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

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

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

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

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

Methods are provided within voucherify.events.* namespace.

• Events

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

voucherify.events.track_event(data);

Methods are provided within voucherify.async_actions.* namespace.

• Get Async Action
• List Async Actions

voucherify.async_actions.get(id);

voucherify.async_actions.list(query);

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.

• Voucherify.new(params) - Voucherify::Client.new(params)
• voucherify.create(voucher) - voucherify.vouchers.create
• voucherify.get(voucher_code) - voucherify.vouchers.get
• voucherify.update(voucher) - voucherify.vouchers.update
• voucherify.list(params) - voucherify.vouchers.list
• voucherify.enable(voucher_code) - voucherify.vouchers.enable
• voucherify.disable(voucher_code) - voucherify.vouchers.disable
• voucherify.publish(campaign_name) - voucherify.distributions.publish
• voucherify.validate(voucher_code, params) - voucherify.validations.validate
• voucherify.redeem(voucher_code, tracking_id) - voucherify.redemptions.redeem
• voucherify.redemption(voucher_code) - voucherify.redemptions.get_for_voucher
• voucherify.redemptions(params) - voucherify.redemptions.list
• voucherify.rollback(redemption_id, tracking_id, reason) - voucherify.redemptions.rollback
• voucherify.create_customer(customer) - voucherify.customers.create
• voucherify.get_customer(customer_id) - voucherify.customers.get
• voucherify.update_customer(customer) - voucherify.customers.update
• voucherify.delete_customer(customer_id) - voucherify.customers.delete
• Utils.round_money(value) - Voucherify::Utils.round_money(value)
• Utils.validate_percent_discount(discount) - Voucherify::Utils.validate_percent_discount(discount)
• Utils.validate_amount_discount(discount) - Voucherify::Utils.validate_amount_discount(discount)
• Utils.validate_unit_discount(discount) - Voucherify::Utils.validate_unit_discount(discount)
• Utils.calculate_price(base_price, voucher, [unit_price]) - Voucherify::Utils.calculate_price(base_price, voucher, [unit_price])
• Utils.calculate_discount(base_price, voucher, [unit_price]) - Voucherify::Utils.calculate_discount(base_price, voucher, [unit_price])

• 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])

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

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.

Bug reports and pull requests are welcome on GitHub at https://github.com/rspective/voucherify-ruby-sdk.

• 2022-01-18 - 4.1.0 - Async Actions support.
• 2021-06-14 - 4.0.0 - Bumped required ruby version, bumped dependencies, added Consents API support, remove deprecated URI.escape.
• 2020-03-09 - 3.0.0 - Bumped required ruby version, bumped dependencies, added list method in Customers module.
• 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

The gem is available as open source under the terms of the MIT License.