Official Voucherify SDK for Ruby

---

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
• Get Voucher
• Update Voucher
• Delete Voucher
• List Vouchers
• Enable Voucher
• Disable Voucher
• Import Vouchers
• Add Gift Voucher Balance

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
• Get Campaign
• Add Voucher to Campaign
• Import Vouchers to Campaign

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
• Create Export
• Get Export
• Delete Export
• List Publications
• Create Publication

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
• Validate Promotion Campaign

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
• List Redemptions
• Get Voucher's Redemptions
• Get Redemption
• Rollback Redemption

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.

• 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.

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
• Get Customer
• Update Customer
• Delete Customer

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
• Get Product
• Update Product
• Delete Product
• List Products
• Create SKU
• Get SKU
• Update SKU
• Delete SKU
• List all product SKUs

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

• Get Validation Rules

• List Validation Rules

• Update Validation Rules

• Delete Validation Rules

• Create Validation Rule Assignment

• List Validation Rule Assignments

• Delete Validation Rule Assignment

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
• Get Segment
• Delete Validation Rules

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.

• Events

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.

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

---

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.