Official Voucherify SDK for Node.js
Migration to 2.x Migration to 4.x | Setup | Callback or Promise? | Error handling | Contributing | Changelog
API: Vouchers | Campaigns | Distributions | Validations | Redemptions | Customers | Consents | Orders | Products | Rewards | Loyalties | Segments | Validation Rules | Promotions | Events | Utils
Setup
npm install voucherify --save
Log-in to Voucherify web interface and obtain your Application Keys from Configuration:
const voucherifyClient = const client =
Optionally, you can add apiVersion
to the client options if you want to use a specific API version.
const client =
API Endpoint
Optionally, you can add apiUrl
to the client options if you want to use Voucherify running in a specific region.
const client =
Callback or Promise?
All methods in the SDK provide both callback based as well as promise based interactions. If you want to use callback just pass it as a last parameter. For example:
clientvouchers
If you prefer to use promises then the code goes like this:
clientvouchers
All other examples in the readme use promises but they could be as well written with callbacks.
API
This SDK is fully consistent with restful API Voucherify provides. You will find detailed description and example responses at official docs. Method headers point to more detailed descriptions of params you can use.
Vouchers API
Methods are provided within client.vouchers.*
namespace.
- Create Voucher
- Get Voucher
- Update Voucher
- Delete Voucher
- Add Gift Voucher Balance
- List Vouchers
- Enable Voucher
- Disable Voucher
- Import Vouchers
- Examine Vouchers Qualification
Create Voucher
clientvouchers
Check voucher object.
Get Voucher
clientvouchers
Update Voucher
clientvouchers
Delete Voucher
clientvouchersclientvouchers
List Vouchers
clientvouchersclientvouchers
Enable Voucher
clientvouchersclientvouchers
Disable Voucher
clientvouchersclientvouchers
Import Vouchers
clientvouchers
Add Gift Voucher Balance
clientvouchersbalance
Examine Vouchers Qualification
clientvouchersqualificationsclientvouchersqualifications// Exampleclientvouchersqualifications
Campaigns API
Methods are provided within client.campaigns.*
namespace.
- Create Campaign
- Update Campaign
- Get Campaign
- Add Voucher to Campaign
- Import Vouchers to Campaign
- List Campaigns
- Examine Campaigns Qualification
Create Campaign
clientcampaigns
Update Campaign
Method will update only fields passed to campaign
argument.
clientcampaignsclientcampaigns
[Delete Campaign]
clientcampaignsclientcampaigns
Get Campaign
clientcampaigns
Add Voucher to Campaign
clientcampaignsclientcampaigns
Import Vouchers to Campaign
clientcampaigns
List Campaigns
Since API version: v2017-04-20
.
clientcampaignsclientcampaigns
Examine Campaigns Qualification
clientcampaignsqualificationsclientcampaignsqualifications// Exampleclientcampaignsqualifications
Distributions API
Methods are provided within client.distributions.*
namespace.
Publish Voucher
clientdistributions
Create Export
clientdistributionsexports
Check the export object.
Get Export
clientdistributionsexports
Delete Export
clientdistributionsexports
List publications
clientdistributionspublicationsclientdistributionspublications
[Create publication]
clientdistributionspublications
Validations API
Methods are provided within client.validations.*
namespace.
Validate Voucher
clientvalidationsclientvalidations // or clientvalidationsclientvalidations
Validate Promotion Campaign
clientvalidations
Redemptions API
Methods are provided within client.redemptions.*
namespace.
- Redeem Voucher
- Redeem Promotion's Tier
- Redeem Loyalty Card
- List Redemptions
- Get Voucher's Redemptions
- Rollback Redemption
Redeem Voucher
clientredemptionsclientredemptions // Deprecated!clientredemptionsclientredemptionsclientredemptions // use: client.redemptions.redeem(code, {customer: {source_id}})
Redeem Loyalty Card
clientredemptions
List Redemptions
clientredemptionsclientredemptions
Get Voucher's Redemptions
clientredemptions
Rollback Redemption
clientredemptionsclientredemptionsclientredemptions
Check redemption rollback object.
Promotions API
Methods are provided within client.promotions.*
namespace.
- Create Promotion Campaign
- Validate Promotion Campaign
- List Promotion's Tiers
- List All Promotion Tiers
- Create Promotion's Tier
- Redeem Promotion's Tier
- Update Promotion's Tier
- Delete Promotion's Tier
Check promotion campaign object.
Create Promotion Campaign
clientpromotions
Validate Promotion Campaign
clientpromotions
List Promotion's Tiers
clientpromotionstiers
Check promotion's tier object
List All Promotion Tiers
clientpromotionstiersclientpromotionstiersclientpromotionstiers
You can list all currently available promotions by specifying is_available
flag.
Create Promotion's Tier
clientpromotionstiers
Redeem Promotion's Tier
clientpromotionstiers
Update Promotion's Tier
clientpromotionstiers
Delete Promotion's Tier
clientpromotionstiers
Customers API
Methods are provided within client.customers.*
namespace.
- Create Customer
- Get Customer
- Update Customer
- Delete Customer
- List Customers
- Update Customer's Consents
Create Customer
clientcustomers
Check customer object.
Get Customer
clientcustomers
Update Customer
customer
object must contain id
or source_id
.
clientcustomers
Delete Customer
clientcustomers
List Customers
clientcustomersclientcustomers
[Scroll through customers]
Standard list customers API has limitation of available pages to be shown equal to 100. To cover cases when you would like to fetch more, you must use scroll capabilities.
{ for await const customer of clientcustomers console }
params
argument is consistent with list
method.
Keep in mind scroll
doesn't support callback version.
You can optionally define scrolling cursor based on customer creation date using property starting_after
.
By default returned customers are in descending order, if you want to change it to ascending define order
equal to create_at
.
{ for await const customer of clientcustomers console }
Keep in mind this operation may drain your API call limits fairly quickly. In the hood it fetches customers in max possible batches of 100. So in example if you have 100'000 customers scroll over all of them, you will use 1000 API calls.
Update Customer's Consents
clientcustomers
Consents API
Methods are provided within client.consents.*
namespace.
You can update Customer's consents in Customer namespace.
List Consents
clientconsents
Orders API
Methods are provided within client.orders.*
namespace.
Create Order
clientorders
Check the order object.
Get Order
clientorders
Update Order
clientorders
List Orders
clientordersclientorders
Products API
Methods are provided within client.products.*
namespace.
- Create Product
- Get Product
- Update Product
- Bulk Update Products
- Delete Product
- List Products
- Create SKU
- Get SKU
- Update SKU
- Delete SKU
- List all product SKUs
Create Product
clientproducts
Check product object.
Get Product
clientproducts
Update Product
clientproducts
Bulk Update Products
clientproducts
Delete Product
clientproductsclientproducts
List Products
clientproductsclientproducts
Create SKU
clientproducts
Check SKU object.
Get SKU
clientproducts
Update SKU
clientproducts
Delete SKU
clientproductsclientproducts
List all product SKUs
clientproducts
Rewards API
Methods are provided within client.rewards.*
namespace.
- Create Reward
- Get Reward
- Update Reward
- Delete Reward
- List Rewards
- Create Reward Assignment
- Update Reward Assignment
- Delete Reward Assignment
- List Reward Assignments
Create Reward
clientrewards
Check reward object.
Get Reward
clientrewards
Update Reward
clientrewards
Delete Reward
clientrewards
List Rewards
clientrewardsclientrewards
Create Reward Assignment
clientrewards
Check reward assignment object.
Update Reward Assignment
clientrewards
[Delete Reward Assignment]
clientrewards
List Reward Assignments
clientrewardsclientrewards
Loyalties API
Methods are provided within client.loyalties.*
namespace.
- Create Loyalty
- Get Loyalty
- Update Loyalty
- Delete Loyalty
- List Loyalties
- Create Loyalty Reward Assignment
- Update Loyalty Reward Assignment
- Delete Loyalty Reward Assignment
- List Loyalty Reward Assignments
- Create Loyalty Earning Rules
- Update Loyalty Earning Rule
- Delete Loyalty Earning Rule
- List Loyalty Earning Rules
- Create Loyalty Member
- Get Loyalty Member
- List Loyalty Members
- Get Member Activites
- Add Points
- Redeem reward
[Create Loyalty]
clientloyalties
[Get Loyalty]
clientloyalties
[Update Loyalty]
clientloyalties
[Delete Loyalty]
clientloyalties
[List Loyalties]
clientloyaltiesclientloyalties
Create Loyalty Reward Assignment
clientloyalties
Update Loyalty Reward Assignment
clientloyalties
Delete Loyalty Reward Assignment
clientloyalties
List Loyalty Reward Assignments
clientloyaltiesclientloyalties
Create Loyalty Earning Rules
clientloyalties
Update Loyalty Earning Rule
clientloyalties
Delete Loyalty Earning Rule
clientloyalties
List Loyalty Earning Rules
clientloyaltiesclientloyalties
Create Loyalty Member
clientloyalties
Get Loyalty Member
clientloyalties
List Loyalty Members
clientloyaltiesclientloyalties
Get Member Activities
clientloyalties
Add Loyalty Card Balance
clientloyalties
Redeem Loyalty Card
clientloyalties
Segments API
Methods are provided within client.segments.*
namespace.
Create Segment
clientsegments
Check the segment object.
Get Segment
clientsegments
Delete Segment
clientsegments
Validation Rules API
Methods are provided within client.validationRules.*
namespace.
- Create Rule
- Get Rule
- Update Rule
- Delete Rule
- Create Rule Assignment
- Delete Rule Assignment
- List Rules
- List Rule Assignments
- Validate Validation Rule
Create Validation Rule
clientvalidationRules
Check validation rule object.
Get Validation Rule
clientvalidationRules
Update Validation Rule
clientvalidationRules
Delete Validation Rule
clientvalidationRules
Create Rule Assignment
clientvalidationRules
Delete Rule Assignment
clientvalidationRules
List Rules
clientvalidationRulesclientvalidationRules
List Rule Assignments
clientvalidationRulesclientvalidationRules
[Validate Validation Rule]
clientvalidationRulesclientvalidationRules
Events API
Methods are provided within client.events.*
namespace.
[Create event]
Check customer object.
clienteventsclienteventsclienteventsclientevents
Migration to 2.x
Version 2.x of the SDK is fully backward compatible with version 1.x. Changes made in version 2.x mostly relate to grouping methods within namespaces. So all you need to do is to follow the list bellow and just replace deprecated methods with their namespaced equivalent.
We also recommend to adopt voucher redemption method, and don't use deprecated invocation.
Migration to 4.x
This version introduces few major changes:
- drops support for node.js v4 and v6
- drops methods previously marked as deprecated, to make transition easier please check table below. All those methods were already available in v3.x.
Previously | Currently |
---|---|
client.events.track(eventName, metadata, customer) |
client.events.create(eventName, { customer, metadata }) |
client.list(params) |
client.vouchers.list(query) |
client.get(voucherCode) |
client.vouchers.get(code) |
client.create(voucher) |
client.vouchers.create(voucher) |
client.update(voucher) |
client.vouchers.update(voucher) |
client.delete(voucherCode, [params]) |
client.vouchers.delete(code, params) |
client.disable(voucherCode) |
client.vouchers.disable(code) |
client.enable(voucherCode) |
client.vouchers.enable(code) |
client.campaign.voucher.create(campaignName) |
client.campaigns.addVoucher(campaignName, voucher) |
client.publish(campaign_name|params) |
client.distributions.publish(campaignName) |
client.validate(voucherCode, params) |
client.validations.validateVoucher(code, params) |
client.redemption(voucherCode) |
client.redemptions.getForVoucher(code) |
client.redeem(voucherCode, tracking_id|params) |
client.redemptions.redeem(code, trackingId) |
client.redemptions(query) |
client.redemptions.list(query) |
client.rollback(redemptionId, params) |
client.redemptions.rollback(redemptionId, data) |
client.customer.* |
changed namespace to client.customers.* |
client.product.* |
changed namespace to client.products.* |
client.product.sku.* |
changed namespace to client.products.* |
Utils
const utils =
Utils don't need callbacks nor promises. They return results immediately.
Available methods
utils.calculatePrice(basePrice, voucher)
utils.calculateDiscount(basePrice, voucher)
utils.webhooks.verifySignature(signature, message, secretKey)
Error handling
Depending what you have choose error
object of rejected Promise or first argument of provided callback has
consistent structure, described in details in our API reference.
Contributing
Bug reports and pull requests are welcome through GitHub Issues.
Changelog
- 2020-09-17 -
5.2.0
- Add support Get Member Activities in Loyality API
- enhancement: throw error objects instead of object literals (@AbdelrahmanHafez)
- dependency update
- Add support for listing all promotion tiers
- Add support for listing consents
- 2020-05-28 -
5.1.0
- adopted API changes in customer scrolling, dropping support for
ending_before
property. This is technically breaking change but we didn't officially released this feature in API so exceptionally we will increase minor version to not confuse SDK users.
- adopted API changes in customer scrolling, dropping support for
- 2020-05-25 -
5.0.0
- [breaking change] Drop support for Node v8
- Add a way to scroll over customers
- Add support for bulk update of products
- 2020-04-06 -
4.2.0
- Add support for Updating Customer's consents - 2020-02-03 -
4.1.0
- expose campaigns and vouchers Qualification API methods - 2019-11-22 -
4.0.0
- Added support for new method
- Distributions
- Publications
- Create
- Publications
- Distributions
- [breaking change] - dropped support for node.js v4 and v6
- Added support for new method
- 2019-06-19 -
3.0.0
- Added support for custom API endpoint, that allows to connect to projects created in specific Voucherify region. - 2019-05-27 -
2.23.0
- Added support for the methods related to the Loyalty Programs- Rewards
- List
- Create
- Get
- Update
- Delete
- Assignments
- List
- Create
- Update
- Delete
- Loyalties
- List
- Create
- Get
- Update
- Delete
- Reward Assignments
- List
- Create
- Update
- Delete
- Earning Rules
- List
- Create
- Update
- Delete
- Members
- List
- Create
- Get
- Add points
- Redeem reward
- Events.create method in Events namespace
- Add methods to delete campaign
- Rewards
- 2019-03-27 -
2.22.0
- Added Validation Rules validate methodclient.validationRules.validate(ruleId, params)
- 2018-12-28 -
2.21.0
- Switch Validation Rules to new model: Business Validation Rules:
- Validation Rule Object - structure reorganized to handle advanced rules
- Validation Rule Assignment Object - added object describing a relation between rules and linked promotions
- Validation Rules - modified data model
- Switch Validation Rules to new model: Business Validation Rules:
- 2018-11-19 -
2.20.0
- Allow updating products and SKUs with given source id - 2018-11-07 -
2.19.0
- Allow to update order with source idclient.orders.update({source_id, ...rest})
- 2018-10-26 -
2.18.0
- Add Update Campaign methodclient.campaigns.update(campaignId, campaign)
- 2018-10-22 -
2.17.0
- Add example of using the
filters
parameter in the method for listing campaigns - Allow zero discount in calc utils
- Add example of using the
- 2018-08-01 -
2.16.0
- Fix reported vulnerabilities (#77) - 2018-06-14 -
2.15.0
- Fixed the way string errors are handled - 2018-03-14 -
2.14.0
- Added util method to Verify Webhooks signature - 2018-01-21 -
2.13.1
- Remove outdatedclient.distributions.publish(campaignName)
method interface - 2017-12-06 -
2.13.0
- Fix voucher validation vulnerability
- Allow to force delete Products and SKUs
- Add Clients listing
- 2017-11-16 -
2.12.0
- Expose Promotions API
- Update Redemptions and Validations namespace
- 2017-10-24 -
2.11.0
- Expose Events API - track events done by the customers - 2017-09-14 -
2.10.0
- Expose Segments API
- Expose Orders API
- Expose Exports API
- Expose Publications list
- 2017-08-29 -
2.8.0
- Expose Campaigns listing
- 2017-08-29 -
2.7.0
- Allow to update Customer by source ID when ID not provided
- 2017-08-09 -
2.6.0
- Add Validation Rules namespace with CRUD methods
- Add Balance namespace with support of Add Gift Voucher Balance method
- 2017-04-21 -
2.5.0
- Add option to override channel. - 2017-04-21 -
2.4.0
- Add option to select specific API version. - 2017-02-20 -
2.3.0
- Add support for node-v0.10 - 2017-02-10 -
2.1.1
- Bugfix missingObject.assign
implementation (touched node-v0.12) - 2017-02-01 -
2.1.0
- Added support for bulk enable/disable vouchers - 2016-12-02 -
2.0.0
- Rewritten SDK, added missing API methods, updated README. Backward capability is provided but we strongly recommend to follow the migration from version 1.x - 2016-12-01 -
1.23.2
- Support gift vouchers in utils - 2016-11-15 -
1.23.1
- Validate init options - 2016-10-26 -
1.23.0
- Error handling improved - passing error object in response to rejected request - 2016-10-03 -
1.22.0
- Added customer parameter to the rollback method - 2016-10-03 -
1.21.1
- Updated documentation according to changes in Publish API method - 2016-09-16 -
1.21.0
- Added method for adding new vouchers to existing campaign - 2016-09-15 -
1.20.0
- Added method for deleting vouchers by code - 2016-09-01 -
1.19.0
- Documentation for evaluating validation rules based on order details - 2016-08-03 -
1.18.1
- Improvements in documentation of SKU API - 2016-08-02 -
1.18.0
- Implemented new API methods- SKU
- Create
- Get
- Update
- Delete
- SKU
- 2016-08-02 -
1.17.0
- Validate voucher - 2016-07-29 -
1.16.0
- Implemented new API methods- Product
- Create
- Get
- Update
- Delete
- Product
- 2016-07-18 -
1.15.0
- Voucher update method. - 2016-06-22 -
1.14.1
- Gift vouchers. - 2016-06-16 -
1.14.0
- Unified naming convention - 2016-06-08 -
1.13.0
- Implemented new API methods- Customer
- Create
- Get
- Update
- Delete
- Customer
- 2016-06-01 -
1.12.0
- tracking_id param removed from redemption rollback method. - 2016-05-24 -
1.11.0
- New publish structure. - 2016-04-26 -
1.10.0
- Rollback redemption. - 2016-04-19 -
1.9.1
- Filter vouchers and redemptions by customer. - 2016-04-08 -
1.9.0
- Added methods to create, disable and enable a voucher. - 2016-04-07 -
1.8.0
- List redemptions with filtering. - 2016-04-04 -
1.7.1
- Updated API URL. - 2016-03-08 -
1.7.0
- List vouchers with filtering. - 2016-01-22 -
1.6.0
- Added publish voucher method. - 2015-12-10 -
1.5.0
- New discount model. Added UNIT - a new discount type. - 2015-11-23 -
1.4.1
- AddedX-Voucherify-Channel
header. - 2015-11-10 -
1.4.0
- AddVoucherifyUtils
which includescalculatePrice
for computing product/cart price after discount andcalculateDiscount
. - 2015-11-05 -
1.3.2
- Updated Readme to snake case naming convention - 2015-10-13 -
1.3.1
- Fixed Readme - 2015-10-12 -
1.3.0
- Changed API after Voucherify's API change- use --> redeem
- usage --> redemption
- 2015-09-25 -
1.2.0
- Ability to track a detailed customer profile that uses a voucher. - 2015-09-24 -
1.1.2
- Small fixes in logging. - 2015-09-11 -
1.1.1
- Updated backend URL. - 2015-08-13 -
1.1.0
- Ability to track use voucher operation.- Properly handling voucher codes with not URL-friendly characters.
- 2015-07-09 -
1.0.1
- Returning to old API URL. - 2015-07-03 -
1.0.0
- Switching API URL. - 2015-07-03 -
0.2.0
- Adding promises support.- You can either:
- Pass a callback in order to use old-school API style.
- Or you can skip the callback and use returned promise.
- You can either:
- 2015-07-03 -
0.1.1
- Publishing package in thenpm
repository. - 2015-07-02 -
0.1.0
- First version:- Authentication
- Voucher informations: get, usage
- Voucher operations: use