The Voucherify Developer Hub

Welcome to the Voucherify developer hub. You'll find comprehensive guides and documentation to help you start working with Voucherify as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

Key concepts

Voucherify offers several building blocks to help you implement promotional campaigns according to your marketing process and e-commerce infrastructure.

Voucherify splits a promo campaign into 5 stages:

  • Defining which customers, products and order structure are eligible for promotion
  • Defining a discount or a reward value
  • Distribution to a customer
  • Validation and redemption of the discount/reward
  • Monitoring promotion performance across customers

Voucherify supports 5 basic promotion models which you can further adjust to your needs: coupon campaign, referral program, gift cards, cart-level promotions, loyalty programs.

Every promotion type implements these 5 stages in a slightly different way but the general approach is the same: Voucherify validates if a customer at the checkout stage is eligible to get a discount/reward. They can be eligible because:

  • they have a code (coupon, referral code, a gift card)
  • they fall into a pre-defined segment automatically (promotions based on cart structure and customer attributes)

Let's look at which Voucherify objects often come into play when implementing promotion workflow. The general idea is the more you stick to our conventions, the less time you need to build your promo software. But we said "often" not without a reason.

Voucherify doesn't want to enforce any rigid structures. After all, the only required action is to call the redemption method and provide something to redeem. We believe this approach should give you and your team the freedom and flexibility to respond to opportunities and changing demands.

Voucherify objects

When you visit Voucherify API reference, you'll notice that the platform provides CRUD endpoints for every object which takes part in promotion workflow. Let's run through the most important ones.


So, let's start off with the most important of these. Every time you want to validate a promotion, irrespective of the type, you need to invoke the redeem method. This will do 2 things: first, it checks if a customer profile and its current context (order structure, attributes) are eligible for a discount, second, it stores a redemption object with details about successful or failed redemption trials. There are 2 things you can redeem, a voucher and promotion tier.

(Read more in Accepting promotions)



Any redemption can be rolled back


A voucher represents a voucher/coupon/promo/referral/gift certificate code. The core feature of a voucher is its code and discount value. Each voucher also has start and expiry date, validity timeframe, code pattern, redemption count limit, status (active/inactive), and link to respective QR, and barcode. A voucher can exist as a standalone instance (e.g. โ€œBlackFridayโ€) or as part of a campaign.

Promotion tier

This object represents a discount which is automatically applied to eligible customers. To define conditions when a promotion should be applied you can use customer attributes and history as well as information about the structure of an order being purchased. The tier also comes with a banner you can display on your web and mobile apps to entice customers to put more into their cart.


Both vouchers and promotion tiers can be grouped into a campaign. In the case of vouchers, the campaign can be used to control and monitor them in bulk. For example, define the number and pattern of generated codes, set expiry dates, deactivate all codes in one click etc. In the case of promotion tiers, it's just a collection of them which you can use when listing active promotions.

Validation rule

Voucherify provides a rule engine which you can use to define the promotion eligibility conditions. They can include various constraints based on:

  • customers - an object storing customer attributes and redemptions made; customers can be grouped in segments (e.g. customers: from London, who redeemed at least once, who purchased for more than $1000 etc.)
  • products - represents your inventory, providing an abstraction for your product catalog structure (products, SKUs, lines, manufacturers etc.). This includes also the product prices directory which allows for validation rules based on a particular price tag (e.g. give 10% if a product costs more than $100)
  • order - stores the context of the transaction being made (total amount, products in the cart, their volume, customer)
  • campaign budget - controls the current promotion performance; e.g. you can stop the campaign if the overall value of the discount that your customers redeemed in a campaign exceeds a given number
  • custom metadata - checks if any custom field coming with a redemption request matches predefined criteria

You can turn on and off various validation rules for single vouchers and promotion tiers and also to groups of them by attaching one to a campaign.

Dynamic segments

Validation rules can work with dynamic data. Let's explain this using one of the most common scenarios - a discount eligible only for new customers. With dynamic segments, you don't have to manually include and exclude customers into a corresponding segment. Read more

Voucherify mechanisms let you define conditions for customers. If a customer object satisfies the criteria it automatically pops into a segment and the redemption will go through successfully. If you change a parameter with the API or dashboard and it doesn't meet your filter settings anymore, it's excluded from the segment real time and further redemption trials will fail. This feature works for built-in fields but also for custom fields which we call metadata.


Voucherify allows you to enhance default objects with custom attributes. Not only can you attach a set of key-value pairs to campaigns, vouchers, customer, product, or redemption but you can also define their schema. Voucherify supports the following types for the custom fields: text, number, flag, date, date time. Additionally, text and number can be restricted by rules like is less than, is equal to, max length etc.

Finally, any custom field can be switched between optional and mandatory. These features allow you to take care of data integrity when you add or modify data with the API or dashboard.


If you want to segment customers around the recency and frequency of a given behavior, you can use custom events. These are objects best suited for tracking high-value customer interactions with your application. Logging a custom event can trigger any number of distributions.

With the custom event metadata field, Voucherify allows you to set properties on custom events. These properties can then be used for further qualifying trigger conditions, increasing personalization in messaging, and generating more sophisticated analytics through the raw data export.


Beside validation rules, you can leverage dynamic segments for delivering promotions to customers at the right time. Voucherify offers several ways to send out promo codes (coupons, referral codes, gift cards) to customers: email, SMS, live chat, push notification etc. Now the best thing is that you can trigger a message which includes a promo code when a customer enters a given segment (e.g. somebody signs up for your newsletter or abandoned their cart or it's the 10th time they purchase in your store). You can also define a static segment and send message to all members at once.

To run a distribution you have to provide a campaign which will feed the promo code tag with a particular unique code. The distribution workflow looks as follows:

  • take a code from a campaign
  • send it with a message via email or another channel
  • mark the code as published so that no one else will get it


As previously said, any built-in distribution channel marks used vouchers as published. Furthermore, if you want to distribute promo codes by your own means (e.g. display on a popup), you can invoke the publish method explicitly. With the publish method, you can yield multiple promo codes with multiple channels at a single request.


A publication event can be used to trigger another distribution


Auto-update campaign

To prevent a situation where a campaign doesn't have enough codes for publication, make sure you use AUTO-UPDATE type.


The other way to trigger distributions is to use orders. In the dashboard, you can create a distribution which listens to changes of order status (CREATED, PAID, CANCELED, FULFILLED). If any order changes its state to the one you defined, the distribution sends a particular customer a message accordingly.

Accepting promotions

OK, so your customers have got a promo code or seen a banner about a cart-level promotion and now want to apply it. To enable this, you need to integrate the respective redemption endpoint with your checkout page. The best way to do this is to install one of our SDKs and call redeem with corresponding arguments.

To improve the checkout experience, you can also consider displaying a discounted price on the client side (web or mobile) just after applying a promotion. To do so, you can use validate voucher, validate promotion endpoints which, for security reasons, you can access with separate client-side API keys. They validate the promotion the same way as the redeem method, but don't create a redemption object. You can also find a web widget which provides a dedicated UI for validation.

Tracking and syncing

There are several ways you can exchange information with Voucherify:

  • API - every major object is equipped, amongst others, with GET or LIST methods
  • CSV import/export - either with the API or dashboard
  • Webhooks - the platform makes callouts for several events


[Sync] id

With the source_id parameter, you can identify Voucherify objects using your reference IDs from CRM/ecommerce systems.


[Sync] dates

Voucherify provides created_at and updated_at fields when you retrieve objects from the API

Recommended reads



You can manage the same promotion flow by using the dashboard and coding-free methods. If you'd like to see a typical Voucherify workflow from a perspective of a marketing team, follow this tutorial.

Updated about a year ago

Key concepts

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.