voucherify

    5.2.0 • Public • Published

    Official Voucherify SDK for Node.js

    JavaScript Style Guide Build Status NPM Version NPM Downloads Dependencies


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

    API Endpoint

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

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

    client.vouchers.create(voucher)

    Check voucher object.

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

    Examine Vouchers Qualification

    client.vouchers.qualifications.examine(bodyParams)
    client.vouchers.qualifications.examine(bodyParams, queryParams)
    // Example
    client.vouchers.qualifications.examine({}, {audienceRulesOnly: true, limit: 10})

    Campaigns API

    Methods are provided within client.campaigns.* namespace.

    Create Campaign

    client.campaigns.create(campaign)

    Update Campaign

    Method will update only fields passed to campaign argument.

    client.campaigns.update(campaignId, campaign)
    client.campaigns.update(campaignName, campaign)

    [Delete Campaign]

    client.campaigns.delete(campaignName)
    client.campaigns.delete(campaignName, {force: true})

    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

    Since API version: v2017-04-20.

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

    Examine Campaigns Qualification

    client.campaigns.qualifications.examine(bodyParams)
    client.campaigns.qualifications.examine(bodyParams, queryParams)
    // Example
    client.campaigns.qualifications.examine({}, {audienceRulesOnly: true, limit: 10})

    Distributions API

    Methods are provided within client.distributions.* namespace.

    Publish Voucher

    client.distributions.publish(params)

    Create Export

    client.distributions.exports.create(exportObject)

    Check the export object.

    Get Export

    client.distributions.exports.get(exportId)

    Delete Export

    client.distributions.exports.delete(exportId)

    List publications

    client.distributions.publications.list()
    client.distributions.publications.list(params)

    [Create publication]

    client.distributions.publications.create(params)

    Validations API

    Methods are provided within client.validations.* namespace.

    Validate Voucher

    client.validations.validateVoucher(code)
    client.validations.validateVoucher(code, params)
     
    // or
     
    client.validations.validate(code)
    client.validations.validate(code, params)

    Validate Promotion Campaign

    client.validations.validate(params)

    Redemptions API

    Methods are provided within client.redemptions.* namespace.

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

    Redeem Loyalty Card

    client.redemptions.redeem(loyaltyCardId, params)

    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.


    Promotions API

    Methods are provided within client.promotions.* namespace.

    Check promotion campaign object.

    Create Promotion Campaign

    client.promotions.create(promotionCampaign)

    Validate Promotion Campaign

    client.promotions.validate(validationContext)

    List Promotion's Tiers

    client.promotions.tiers.list(promotionCampaignId)

    Check promotion's tier object

    List All Promotion Tiers

    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.

    Create Promotion's Tier

    client.promotions.tiers.create(promotionId, promotionsTier)

    Redeem Promotion's Tier

    client.promotions.tiers.redeem(promotionsTierId, redemptionContext)

    Update Promotion's Tier

    client.promotions.tiers.update(promotionsTier)

    Delete Promotion's Tier

    client.promotions.tiers.delete(promotionsTierId)

    Customers API

    Methods are provided within client.customers.* namespace.

    Create Customer

    client.customers.create(customer)

    Check customer object.

    Get Customer

    client.customers.get(customerId)

    Update Customer

    customer object must contain id or source_id.

    client.customers.update(customer)

    Delete Customer

    client.customers.delete(customerId)

    List Customers

    client.customers.list()
    client.customers.list(params)

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

    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.

    Update Customer's Consents

    client.customers.updateConsents(customer, consents)

    Consents API

    Methods are provided within client.consents.* namespace.

    You can update Customer's consents in Customer namespace.

    List Consents

    client.consents.list()

    Orders API

    Methods are provided within client.orders.* namespace.

    Create Order

    client.orders.create(order)

    Check the order object.

    Get Order

    client.orders.get(orderId)

    Update Order

    client.orders.update(order)

    List Orders

    client.orders.list()
    client.orders.list(params)

    Products API

    Methods are provided within client.products.* namespace.

    Create Product

    client.products.create(product)

    Check product object.

    Get Product

    client.products.get(productId)

    Update Product

    client.products.update(product)

    Bulk Update Products

    client.products.bulkUpdate(products)

    Delete Product

    client.products.delete(productId)
    client.products.delete(productId, {force: true})

    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)
    client.products.deleteSku(productId, skuId, {force: true})

    List all product SKUs

    client.products.listSkus(productId)

    Rewards API

    Methods are provided within client.rewards.* namespace.

    Create Reward

    client.rewards.create(reward)

    Check reward object.

    Get Reward

    client.rewards.get(rewardId)

    Update Reward

    client.rewards.update(reward)

    Delete Reward

    client.rewards.delete(rewardId)

    List Rewards

    client.rewards.list()
    client.rewards.list(params)

    Create Reward Assignment

    client.rewards.createAssignment(rewardId, assignment)

    Check reward assignment object.

    Update Reward Assignment

    client.rewards.updateAssignment(rewardId, assignment)

    [Delete Reward Assignment]

    client.rewards.deleteAssignment(rewardId, assignmentId)

    List Reward Assignments

    client.rewards.listAssignments(rewardId)
    client.rewards.listAssignments(rewardId, params)

    Loyalties API

    Methods are provided within client.loyalties.* namespace.

    [Create Loyalty]

    client.loyalties.create(campaign)

    [Get Loyalty]

    client.loyalties.get(campaignId)

    [Update Loyalty]

    client.loyalties.update(campaign)

    [Delete Loyalty]

    client.loyalties.delete(campaignId)

    [List Loyalties]

    client.loyalties.list()
    client.loyalties.list(params)

    Create Loyalty Reward Assignment

    client.loyalties.createRewardAssignments(campaignId, assignment)

    Update Loyalty Reward Assignment

    client.loyalties.updateRewardAssignment(campaignId, assignment)

    Delete Loyalty Reward Assignment

    client.loyalties.deleteRewardAssignment(campaignId, assignmentId)

    List Loyalty Reward Assignments

    client.loyalties.listRewardAssignments(campaignId)
    client.loyalties.listRewardAssignments(campaignId, params)

    Create Loyalty Earning Rules

    client.loyalties.createEarningRule(campaignId, earningRules)

    Update Loyalty Earning Rule

    client.loyalties.updateEarningRule(campaignId, earningRule)

    Delete Loyalty Earning Rule

    client.loyalties.deleteEarningRule(campaignId, earningRuleId)

    List Loyalty Earning Rules

    client.loyalties.listEarningRules(campaignId)
    client.loyalties.listEarningRules(campaignId, params)

    Create Loyalty Member

    client.loyalties.createMember(campaignId, member)

    Get Loyalty Member

    client.loyalties.getMember(campaignId, memberId)

    List Loyalty Members

    client.loyalties.listMembers(campaignId)
    client.loyalties.listMembers(campaignId, params)

    Get Member Activities

    client.loyalties.getMemberActivities(campaignId, memberId)

    Add Loyalty Card Balance

    client.loyalties.addPoints(campaignId, memberId, balance)

    Redeem Loyalty Card

    client.loyalties.redeemReward(campaignId, memberId, reward)

    Segments API

    Methods are provided within client.segments.* namespace.

    Create Segment

    client.segments.create(segment)

    Check the segment object.

    Get Segment

    client.segments.get(segmentId)

    Delete Segment

    client.segments.delete(segmentId)

    Validation Rules API

    Methods are provided within client.validationRules.* namespace.

    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)

    Create Rule Assignment

    client.validationRules.createAssignment(validationRuleId, assignment)

    Delete Rule Assignment

    client.validationRules.deleteAssignment(validationRuleId, assignmentId)

    List Rules

    client.validationRules.list()
    client.validationRules.list(params)

    List Rule Assignments

    client.validationRules.listAssignments(validationRuleId)
    client.validationRules.listAssignments(validationRuleId, params)

    [Validate Validation Rule]

    client.validationRules.validate(validationRuleId)
    client.validationRules.validate(validationRuleId, params)

    Events API

    Methods are provided within client.events.* namespace.

    [Create event]

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

    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 = require('voucherify/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.
    • 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
      • [breaking change] - dropped support for node.js v4 and v6
    • 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
    • 2019-03-27 - 2.22.0 - Added Validation Rules validate method client.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
    • 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 id client.orders.update({source_id, ...rest})
    • 2018-10-26 - 2.18.0 - Add Update Campaign method client.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
    • 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 outdated client.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 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

    Install

    npm i voucherify

    DownloadsWeekly Downloads

    7,701

    Version

    5.2.0

    License

    MIT

    Unpacked Size

    81 kB

    Total Files

    29

    Last publish

    Collaborators

    • rspective