search

voucherifyio / voucherify-nodejs-sdk

[Deprecated] Node.js SDK for Voucherify - coupons, vouchers, promo codes
http://www.voucherify.io
MIT License
27 stars 16 forks source link
nodejs sdk voucher

readme

This repository is no longer actively maintained, we have a new SDK for node.js at voucherifyio/voucherify-js-sdk. Check migration guide.

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:

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

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