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:

  1. Defining which customers, products, and order structures are eligible for the promotion.
  2. Defining a discount or a reward value.
  3. Sharing codes with customers.
  4. Validating and redeeming the discount/reward.
  5. Monitoring promotion performance across customers and channels.

Voucherify supports six basic campaign types which you can further adjust to your needs:
- coupon campaigns,
- referral programs,
- gift cards,
- cart-level promotions,
- loyalty programs,
- giveaways.

Every promotion type implements these five 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 match predefined promotion conditions (in-cart promotions based on cart structure and customer attributes).

Let's look at which Voucherify objects often come into play when implementing campaign 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.


Let's start off with the most important of these. Irrespective of the campaign type, every time you want to apply incentive to customer's cart, you need to invoke the redemption. This will do two things: first, it validates if a customer and the 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 three things you can redeem:

(Read more in Accepting promotions)



Any redemption can be rolled back


A voucher represents a voucher/coupon/referral/gift certificate code. The core feature of a voucher is its code and discount value. Each voucher also has a 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.


Coupons Ultimate Guide

Go here to learn more about available coupon campaigns and discoutn types.

Promotion tier

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


Promotion setup

Learn how to setup a cart-level promotion.


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 that you can use when listing active promotions. Besides coupon and gifts campaigns, you can create referral programs and loyalty campaigns.


Your first promo campaign

This tutorial will guide you through the setup of your first campaign.

Validation rule

Voucherify provides a rules engine which you can use to define the campaign limits and loyalty earning rules. They can include various constraints based on:

  • Customers – stores customer attributes and activity; 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 amount.
  • Metadata – checks if custom fields assigned to customer, product, order or redemption matches predefined criteria.


Validation rules and limits reference

Here's a list and descrpition of all available validation rules and campaign limits.

Dynamic segments

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

Voucherify lets 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 in real-time and further redemption attempts will fail. This feature works for built-in fields and custom fields which we call metadata. Learn more about segments.


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, image URL, object, geopoint. 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. Now, you can also create nested metadata and arrays.


Customize with metadata

Go here to learn how to use metadata in your campaigns and boost personalization.


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 to further qualify trigger conditions, personalize messaging, and generate more sophisticated analytics through the raw data export.


Besides 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) and messages to customers: email, SMS, live chat, push notification, etc. The best thing is that you can trigger a message automatically in response to a predefined action (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 manual messages to all members at once.



Learn how to use Distributions.


Publication is the process of assigning a promo code to a particular customer. Each unique code can be published to one customer only. As previously said, any built-in distribution channel publishes and sends vouchers to a predefined audience. Furthermore, if you want to distribute promo codes by your own means (e.g., display on a popup), you can invoke the publish method. With the publish method, you can yield multiple promo codes with multiple channels at a single request. A publication event can be also used to trigger another distribution.



Learn how to manage Publications.


Auto-update campaign

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


If you connected your system to Orders API, you will see new records every time your customers create a new order. The Orders tab helps you track your customers' orders and all transactional activities. You can manage orders by using the Dashboard or via API.

In the dashboard, you can create a distribution that listens to changes of the order status (CREATED, PAID, CANCELED, FULFILLED). If any order changes its state to the one you defined, the distribution sends a message to the particular customer. Read more about orders.

Accepting promotions

When your customers have a promo code or saw a banner about a cart-level promotion, they maight 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 code/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.

Go here to read a complete guide on tracking and reporting.


[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


Important note

We highly recommend to create campaigns and validation rules in the dashboard. You can use API (or dashboard) to monitor, track, and maintain your campaigns. It's not recommended to create campaigns or rules via API.

Did this page help you?