Skip to content

Voucherify SDK for JavaScript and node.js – coupons, vouchers, promo codes


Notifications You must be signed in to change notification settings


Repository files navigation

Official Voucherify JS SDK and React Widget

Build Status SDK NPM Version SDK NPM Downloads React Widget NPM Version React Widget NPM Downloads

Documentation | Marketer-ready Voucherify snippet | Migration | Typescript | Error handling | Legacy SDKs | Contributing | Changelog

Packages: Voucherify JS SDK | Voucherify React Widget

Voucherify empowers marketers and developers with flexible building blocks to come up with, implement, and track targeted promotional campaigns.

Learn more about Voucherify by visiting our site.

📝 Documentation

You will find detailed description and example responses at our official documentation. Most method headers point to more detailed descriptions of arguments you can use.

You can also use our detailed documentation provided by our package here.

📚 Want to learn more? Visit our official site or our Success Portal.

👽 Having troubles? Check our Help center.

🧪 Looking for promotion ideas? Check our Cookbook to get an inspiration.

⚙️ Installation

Voucherify JS SDK

Voucherify JS SDK is a JavaScript SDK which is fully consistent with restful API Voucherify provides and has fully integrated TypeScript support. It also combines together our previously maintained Voucherify Node.js SDK and Voucherify.js.

Go here to learn more about Voucherify JS SDK installation.

Voucherify React Widget

Voucherify React Widget contains several client-side Voucherify methods, which are useful in integrating your promotion logic straight to your e-commerce store.

Go here to learn more about Voucherify React Widget installation.

🏎 Marketer-ready Voucherify snippet

Go here for more HTML-based examples

  <div id="voucher-validate"></div>

  <link rel="stylesheet" type="text/css" href="" />
  <script src="" crossorigin></script>
  <script src="" crossorigin></script>
  <script src="" crossorigin></script>
  <script src="" crossorigin></script>
  <script type="text/javascript" src="" crossorigin></script>
  <script type="text/javascript" src="" crossorigin></script>

  <script type="text/javascript">
      window.React.createElement(VoucherifyWidget.VoucherifyValidate, {
        clientApplicationId: 'CLIENT-APPLICATION-ID',
        clientSecretKey: 'CLIENT-SECRET-KEY',
        amount: true,

Alternative way - iframe and jQuery

In case you're looking for something plain and simple, you're used to working with iframes and jQuery on your website, and for whatever technical reason the aforementioned React-based snippet doesn't work for you, then you might want to stick with our legacy voucherify.js SDK for the time being. In such case, please refer to the widget section in the documentation.

↔️ Migration

Check out MIGRATION GUIDE to learn more about switching to the newest Voucherify JS SDK.

🦸 TypeScript

Both Voucherify JS SDK and Voucherify React Widget support TypeScript declarations. We recommend using TypeScript Version 4.2.

You can find TS example in examples/sdk/with-nodejs-typescript.

😨 Error handling

Voucherify error object always has consistent structure, described in details in our API reference.

If you wish to see code examples for server-side error handling, you can check it here:

Structure / typing for error returned from Voucherify API can be seen here:

If you wish to receive original AxiosError when VoucherifyError is thrown then you need to explicitly set exposeErrorCause property to true when creating instance of VouchierfyClient, ie:

const voucherify = VoucherifyServerSide({
	applicationId: 'APPLICATION-ID',
	secretKey: 'SECRET-KEY',
	exposeErrorCause: true

Original AxiosError will be available under cause property of VoucherifyError

👴 Legacy Voucherify JS SDKs

Legacy client-side Voucherify JS SDK is available here: voucherify.js.

Legacy server-side Voucherify JS SDK is available here: voucherify-nodejs-sdk.

🛠️ Contributing

Bug reports and pull requests are welcome through GitHub Issues.

Read more about how to Contribute to Voucherify JS SDK by visiting

🗄️ Changelog

Voucherify React Widget CHANGELOG can be found here.

Voucherify JS SDK CHANGELOG can be found here.

🧪 SDK Tests

Sdk tests are located in packages/sdk/tests and uses real calls to voucherify API via client.ts.

// add this in your test
import { voucherifyClient as client } from './client'

In order to run sdk tests you need to copy packages/sdk/.env.example to packages/sdk/.env and fill the file with your credentials.

In order to run sdk tests please go to packages/sdk folder and run yarn test