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
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, )
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.
- 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
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
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, , 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.createvoucherify.get(voucher_code)
- voucherify.vouchers.getvoucherify.update(voucher)
- voucherify.vouchers.updatevoucherify.list(params)
- voucherify.vouchers.listvoucherify.enable(voucher_code)
- voucherify.vouchers.enablevoucherify.disable(voucher_code)
- voucherify.vouchers.disablevoucherify.publish(campaign_name)
- voucherify.distributions.publishvoucherify.validate(voucher_code, params)
- voucherify.validations.validatevoucherify.redeem(voucher_code, tracking_id)
- voucherify.redemptions.redeemvoucherify.redemption(voucher_code)
- voucherify.redemptions.get_for_vouchervoucherify.redemptions(params)
- voucherify.redemptions.listvoucherify.rollback(redemption_id, tracking_id, reason)
- voucherify.redemptions.rollbackvoucherify.create_customer(customer)
- voucherify.customers.createvoucherify.get_customer(customer_id)
- voucherify.customers.getvoucherify.update_customer(customer)
- voucherify.customers.updatevoucherify.delete_customer(customer_id)
- voucherify.customers.deleteUtils.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 codemessage
- 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 errorkey
- 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.
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-05-09 -
2.3.0
- Addedcreate_publication
method in Distributions module.. - 2019-04-23 -
2.2.0
- Loyalties API, Rewards API, Orders API. - 2019-02-19 -
2.1.1
- Treatreferral
as optional in custom events. Added new method for custom event tracking. - 2019-02-19 -
2.1.0
- Handlereferral
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 topry
- 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.