voucherify
Advanced tools
Readme
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
npm install voucherify --save
Log-in to Voucherify web interface and obtain your Application Keys from Configuration:
const voucherifyClient = require('voucherify')
const client = voucherifyClient({
applicationId: 'YOUR-APPLICATION-ID',
clientSecretKey: 'YOUR-CLIENT-SECRET-KEY'
})
Optionally, you can add apiVersion to the client options if you want to use a specific API version.
const client = voucherifyClient({
applicationId: 'YOUR-APPLICATION-ID',
clientSecretKey: 'YOUR-CLIENT-SECRET-KEY',
apiVersion: 'v2017-04-20'
})
Optionally, you can add apiUrl to the client options if you want to use Voucherify running in a specific region.
const client = voucherifyClient({
applicationId: 'YOUR-APPLICATION-ID',
clientSecretKey: 'YOUR-CLIENT-SECRET-KEY',
apiUrl: 'https://<region>.api.voucherify.io'
})
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:
client.vouchers.get('v1GiJYuuS', (error, result) => {
if (error) {
// handle error
return
}
// do the work
})
If you prefer to use promises then the code goes like this:
client.vouchers.get('v1GiJYuuS')
.then((result) => {
console.log(result)
})
.catch((error) => {
console.error("Error: %s", error)
})
All other examples in the readme use promises but they could be as well written with callbacks.
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.
Methods are provided within client.vouchers.* namespace.
client.vouchers.create(voucher)
Check voucher object.
client.vouchers.get(code)
client.vouchers.update(voucher)
client.vouchers.delete(code)
client.vouchers.delete(code, {force: true})
client.vouchers.list()
client.vouchers.list(params)
client.vouchers.enable()
client.vouchers.enable(code)
client.vouchers.disable()
client.vouchers.disable(code)
client.vouchers.import(vouchers)
client.vouchers.balance.create(code, {amount})
client.vouchers.qualifications.examine(bodyParams)
client.vouchers.qualifications.examine(bodyParams, queryParams)
// Example
client.vouchers.qualifications.examine({}, {audienceRulesOnly: true, limit: 10})
Methods are provided within client.campaigns.* namespace.
client.campaigns.create(campaign)
Method will update only fields passed to campaign argument.
client.campaigns.update(campaignId, campaign)
client.campaigns.update(campaignName, campaign)
client.campaigns.delete(campaignName)
client.campaigns.delete(campaignName, {force: true})
client.campaigns.get(name)
client.campaigns.addVoucher(campaignName)
client.campaigns.addVoucher(campaignName, params)
client.campaigns.importVouchers(campaignName, vouchers, callback)
Since API version: v2017-04-20.
client.campaigns.list()
client.campaigns.list(params)
client.campaigns.qualifications.examine(bodyParams)
client.campaigns.qualifications.examine(bodyParams, queryParams)
// Example
client.campaigns.qualifications.examine({}, {audienceRulesOnly: true, limit: 10})
Methods are provided within client.distributions.* namespace.
client.distributions.publish(params)
client.distributions.exports.create(exportObject)
Check the export object.
client.distributions.exports.get(exportId)
client.distributions.exports.delete(exportId)
client.distributions.publications.list()
client.distributions.publications.list(params)
client.distributions.publications.create(params)
Methods are provided within client.validations.* namespace.
client.validations.validateVoucher(code)
client.validations.validateVoucher(code, params)
// or
client.validations.validate(code)
client.validations.validate(code, params)
client.validations.validate(params)
Methods are provided within client.redemptions.* namespace.
client.redemptions.redeem(code)
client.redemptions.redeem(code, params)
// Deprecated!
client.redemptions.redeem({code, ...params})
client.redemptions.redeem({code, ...params}, tracking_id)
client.redemptions.redeem(code, tracking_id) // use: client.redemptions.redeem(code, {customer: {source_id}})
client.redemptions.redeem(loyaltyCardId, params)
client.redemptions.list()
client.redemptions.list(params)
client.redemptions.getForVoucher(code)
client.redemptions.rollback(redemptionId)
client.redemptions.rollback(redemptionId, params)
client.redemptions.rollback(redemptionId, reason)
Check redemption rollback object.
Methods are provided within client.promotions.* namespace.
Check promotion campaign object.
client.promotions.create(promotionCampaign)
client.promotions.validate(validationContext)
client.promotions.tiers.list(promotionCampaignId)
Check promotion's tier object
client.promotions.tiers.listAll()
client.promotions.tiers.listAll({ is_available: true })
client.promotions.tiers.listAll({ page: 2, limit: 10 })
You can list all currently available promotions by specifying is_available flag.
client.promotions.tiers.create(promotionId, promotionsTier)
client.promotions.tiers.redeem(promotionsTierId, redemptionContext)
client.promotions.tiers.update(promotionsTier)
client.promotions.tiers.delete(promotionsTierId)
Methods are provided within client.customers.* namespace.
client.customers.create(customer)
Check customer object.
client.customers.get(customerId)
customer object must contain id or source_id.
client.customers.update(customer)
client.customers.delete(customerId)
client.customers.list()
client.customers.list(params)
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.
async function () {
for await (const customer of client.customers.scroll(params)) {
console.log('Customer', customer)
}
}
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.
async function () {
for await (const customer of client.customers.scroll({
starting_after: "2020-01-01", // optional
order: "create_at" // optional (by default order is "-create_at" which corresponds to descending).
...params})
) {
console.log('Customer', customer)
}
}
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.
client.customers.updateConsents(customer, consents)
Methods are provided within client.consents.* namespace.
You can update Customer's consents in Customer namespace.
client.consents.list()
Methods are provided within client.orders.* namespace.
client.orders.create(order)
Check the order object.
client.orders.get(orderId)
client.orders.update(order)
client.orders.list()
client.orders.list(params)
Methods are provided within client.products.* namespace.
client.products.create(product)
Check product object.
client.products.get(productId)
client.products.update(product)
client.products.bulkUpdate(products)
client.products.delete(productId)
client.products.delete(productId, {force: true})
client.products.list()
client.products.list(params)
client.products.createSku(productId, sku)
Check SKU object.
client.products.getSku(productId, skuId)
client.products.updateSku(productId, sku)
client.products.deleteSku(productId, skuId)
client.products.deleteSku(productId, skuId, {force: true})
client.products.listSkus(productId)
Methods are provided within client.rewards.* namespace.
client.rewards.create(reward)
Check reward object.
client.rewards.get(rewardId)
client.rewards.update(reward)
client.rewards.delete(rewardId)
client.rewards.list()
client.rewards.list(params)
client.rewards.createAssignment(rewardId, assignment)
Check reward assignment object.
client.rewards.updateAssignment(rewardId, assignment)
client.rewards.deleteAssignment(rewardId, assignmentId)
client.rewards.listAssignments(rewardId)
client.rewards.listAssignments(rewardId, params)
Methods are provided within client.loyalties.* namespace.
client.loyalties.create(campaign)
client.loyalties.get(campaignId)
client.loyalties.update(campaign)
client.loyalties.delete(campaignId)
client.loyalties.list()
client.loyalties.list(params)
client.loyalties.createRewardAssignments(campaignId, assignment)
client.loyalties.updateRewardAssignment(campaignId, assignment)
client.loyalties.deleteRewardAssignment(campaignId, assignmentId)
client.loyalties.listRewardAssignments(campaignId)
client.loyalties.listRewardAssignments(campaignId, params)
client.loyalties.createEarningRule(campaignId, earningRules)
client.loyalties.updateEarningRule(campaignId, earningRule)
client.loyalties.deleteEarningRule(campaignId, earningRuleId)
client.loyalties.listEarningRules(campaignId)
client.loyalties.listEarningRules(campaignId, params)
client.loyalties.createMember(campaignId, member)
client.loyalties.getMember(campaignId, memberId)
client.loyalties.listMembers(campaignId)
client.loyalties.listMembers(campaignId, params)
client.loyalties.getMemberActivities(campaignId, memberId)
client.loyalties.addPoints(campaignId, memberId, balance)
client.loyalties.redeemReward(campaignId, memberId, reward)
Methods are provided within client.segments.* namespace.
client.segments.create(segment)
Check the segment object.
client.segments.get(segmentId)
client.segments.delete(segmentId)
Methods are provided within client.validationRules.* namespace.
client.validationRules.create(validationRule)
Check validation rule object.
client.validationRules.get(validationRuleId)
client.validationRules.update(validationRule)
client.validationRules.delete(validationRuleId)
client.validationRules.createAssignment(validationRuleId, assignment)
client.validationRules.deleteAssignment(validationRuleId, assignmentId)
client.validationRules.list()
client.validationRules.list(params)
client.validationRules.listAssignments(validationRuleId)
client.validationRules.listAssignments(validationRuleId, params)
client.validationRules.validate(validationRuleId)
client.validationRules.validate(validationRuleId, params)
Methods are provided within client.events.* namespace.
Check customer object.
client.events.create(eventName, { customer })
client.events.create(eventName, { customer, metadata })
client.events.create(eventName, { customer, referral, metadata })
client.events.create(eventName, { customer, referral, loyalty, metadata })
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.
This version introduces few major changes:
| 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.validate(voucherCode, params) | client.validations.validateVoucher(code, params) |
client.redemption(voucherCode) | client.redemptions.getForVoucher(code) |
| `client.redeem(voucherCode, tracking_id | params)` |
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.* |
const utils = require('voucherify/utils')
Utils don't need callbacks nor promises. They return results immediately.
utils.calculatePrice(basePrice, voucher)utils.calculateDiscount(basePrice, voucher)utils.webhooks.verifySignature(signature, message, secretKey)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.
Bug reports and pull requests are welcome through GitHub Issues.
5.2.0
5.1.0
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.5.0.0
4.2.0 - Add support for Updating Customer's consents4.1.0 - expose campaigns and vouchers Qualification API methods4.0.0
3.0.0 - Added support for custom API endpoint, that allows to connect to projects created in specific Voucherify region.2.23.0 - Added support for the methods related to the Loyalty Programs
2.22.0 - Added Validation Rules validate method client.validationRules.validate(ruleId, params)2.21.0
2.20.0 - Allow updating products and SKUs with given source id2.19.0 - Allow to update order with source id client.orders.update({source_id, ...rest})2.18.0 - Add Update Campaign method client.campaigns.update(campaignId, campaign)2.17.0
filters parameter in the method for listing campaigns2.16.0 - Fix reported vulnerabilities (#77)2.15.0 - Fixed the way string errors are handled2.14.0 - Added util method to Verify Webhooks signature2.13.1 - Remove outdated client.distributions.publish(campaignName) method interface2.13.0
2.12.0
2.11.0 - Expose Events API - track events done by the customers2.10.0
2.8.0
2.7.0
2.6.0
2.5.0 - Add option to override channel.2.4.0 - Add option to select specific API version.2.3.0 - Add support for node-v0.102.1.1 - Bugfix missing Object.assign implementation (touched node-v0.12)2.1.0 - Added support for bulk enable/disable vouchers2.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.x1.23.2 - Support gift vouchers in utils1.23.1 - Validate init options1.23.0 - Error handling improved - passing error object in response to rejected request1.22.0 - Added customer parameter to the rollback method1.21.1 - Updated documentation according to changes in Publish API method1.21.0 - Added method for adding new vouchers to existing campaign1.20.0 - Added method for deleting vouchers by code1.19.0 - Documentation for evaluating validation rules based on order details1.18.1 - Improvements in documentation of SKU API1.18.0 - Implemented new API methods
1.17.0 - Validate voucher1.16.0 - Implemented new API methods
1.15.0 - Voucher update method.1.14.1 - Gift vouchers.1.14.0 - Unified naming convention1.13.0 - Implemented new API methods
1.12.0 - tracking_id param removed from redemption rollback method.1.11.0 - New publish structure.1.10.0 - Rollback redemption.1.9.1 - Filter vouchers and redemptions by customer.1.9.0 - Added methods to create, disable and enable a voucher.1.8.0 - List redemptions with filtering.1.7.1 - Updated API URL.1.7.0 - List vouchers with filtering.1.6.0 - Added publish voucher method.1.5.0 - New discount model. Added UNIT - a new discount type.1.4.1 - Added X-Voucherify-Channel header.1.4.0 - Add VoucherifyUtils which includes calculatePrice for computing product/cart price
after discount and calculateDiscount.1.3.2 - Updated Readme to snake case naming convention1.3.1 - Fixed Readme1.3.0 - Changed API after Voucherify's API change
1.2.0 - Ability to track a detailed customer profile that uses a voucher.1.1.2 - Small fixes in logging.1.1.1 - Updated backend URL.1.1.0 - Ability to track use voucher operation.
1.0.1 - Returning to old API URL.1.0.0 - Switching API URL.0.2.0 - Adding promises support.
0.1.1 - Publishing package in the npm repository.0.1.0 - First version:
FAQs
Official Voucherify SDK for Node.js
The npm package voucherify receives a total of 2,480 weekly downloads. As such, voucherify popularity was classified as popular.
We found that voucherify demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Streamline your login process and enhance security by enabling Single Sign-On (SSO) on the Socket platform, now available for all customers on the Enterprise plan, supporting 20+ identity providers.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.