nitzo/voucherify-nodejs-sdk

Official Voucherify SDK for Node.js

Setup

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 clientV20170420 = voucherifyClient({
    applicationId: 'YOUR-APPLICATION-ID',
    clientSecretKey: 'YOUR-CLIENT-SECRET-KEY',
    apiVersion: 'v2017-04-20'
})

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:

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.

API

This SDK is fully consistent with restufl API Voucherify provides. Detalied description and example responses you will find at official docs. Method headers point to more detalied params description 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

Create Voucher

client.vouchers.create(voucher)

Check voucher oject.

Get Voucher

client.vouchers.get(code)

Update Voucher

client.vouchers.update(voucher)

Delete Voucher

client.vouchers.delete(code)
client.vouchers.delete(code, {force: true})

List Vouchers

client.vouchers.list()
client.vouchers.list(params)

Enable Voucher

client.vouchers.enable()
client.vouchers.enable(code)

Disable Voucher

client.vouchers.disable()
client.vouchers.disable(code)

Import Vouchers

client.vouchers.import(vouchers)

Add Gift Voucher Balance

client.vouchers.balance.create({code, amount})

Campaigns API

Methods are provided within client.campaigns.* namespace.

Create Campaign
Get Campaign
Add Voucher to Campaign
Import Vouchers to Campaign
List Campaigns

Create Campaign

client.campaigns.create(campaign)

Get Campaign

client.campaigns.get(name)

Add Voucher to Campaign

client.campaigns.addVoucher(campaignName)
client.campaigns.addVoucher(campaignName, params)

Import Vouchers to Campaign

client.campaigns.importVouchers(campaignName, vouchers, callback)

List Campaigns

client.campaigns.list()
client.campaigns.list(params)

Distributions API

Methods are provided within client.distributions.* namespace.

Publish Voucher

client.distributions.publish(campaignName)
client.distributions.publish(params)

Validations API

Methods are provided within client.validations.* namespace.

Validate Voucher

client.validations.validateVoucher(code)
client.validations.validateVoucher(code, params)

Redemptions API

Methods are provided within client.redemptions.* namespace.

Redeem Voucher
List Redemptions
Get Voucher's Redemptions
Rollback Redemption

Redeem Voucher

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

List Redemptions

client.redemptions.list()
client.redemptions.list(params)

Get Voucher's Redemptions

client.redemptions.getForVoucher(code)

Rollback Redemption

client.redemptions.rollback(redemptionId)
client.redemptions.rollback(redemptionId, params)
client.redemptions.rollback(redemptionId, reason)

Check redemption rollback object.

Customers API

Methods are provided within client.customers.* namespace.

Create Customer
Get Customer
Update Customer
Delete Customer

Create Customer

client.customers.create(customer)

Check customer object.

Get Customer

client.customers.get(customerId)

Update Customer

client.customers.update(customer)

Delete Customer

client.customers.delete(customerId)

Products API

Methods are provided within client.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

client.products.create(product)

Check product object.

Get Product

client.products.get(productId)

Update Product

client.products.update(product)

Delete Product

client.products.delete(productId)

List Products

client.products.list()
client.products.list(params)

Create SKU

client.products.createSku(productId, sku)

Check SKU object.

Get SKU

client.products.getSku(productId, skuId)

Update SKU

client.products.updateSku(productId, sku)

Delete SKU

client.products.deleteSku(productId, skuId)

List all product SKUs

client.products.listSkus(productId)

Validation Rules API

Methods are provided within client.validationRules.* namespace.

Create Rule
Get Rule
Update Rule
Delete Rule

Create Validation Rule

client.validationRules.create(validationRule)

Check validation rule object.

Get Validation Rule

client.validationRules.get(validationRuleId)

Update Validation Rule

client.validationRules.update(validationRule)

Delete Validation Rule

client.validationRules.delete(validationRuleId)

Migration from 1.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.

Deprecated methods

client.list(params) - client.vouchers.list
client.get(voucherCode) - client.vouchers.get
client.create(voucher) - client.vouchers.create
client.update(voucher) - client.vouchers.update
client.delete(voucherCode, [params]) - client.vouchers.delete
client.disable(voucherCode) - client.vouchers.disable
client.enable(voucherCode) - client.vouchers.enable
client.campaign.voucher.create(campaignName) - client.campaigns.addVoucher
client.redemption(voucherCode) - client.redemptions.getForVoucher
client.publish(campaign_name|params) - client.distributions.publish
client.validate(voucherCode, params) - client.validations.validateVoucher
client.redeem(voucherCode, tracking_id|params) - client.redemptions.redeem
client.redemptions(params) - client.redemptions.list
client.rollback(redemptionId, params) - client.redemptions.rollback
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 = require('voucherify/utils')

Utils don't need callbacks nor promises. They return results immediately.

Available methods

utils.calculatePrice(basePrice, voucher)
utils.calculateDiscount(basePrice, voucher)

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

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 missing Object.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
2016-08-02 - 1.17.0 - Validate voucher
2016-07-29 - 1.16.0 - Implemented new API methods
- Product
  - Create
  - Get
  - Update
  - Delete
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
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 - Added X-Voucherify-Channel header.
2015-11-10 - 1.4.0 - Add VoucherifyUtils which includes calculatePrice for computing product/cart price after discount and calculateDiscount.
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.
2015-07-03 - 0.1.1 - Publishing package in the npm repository.
2015-07-02 - 0.1.0 - First version:
- Authentication
- Voucher informations: get, usage
- Voucher operations: use