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 structures are eligible for the promotion.
  • Defining a discount or a reward value.
  • Sharing codes with customers.
  • Validating and redeeming the discount/reward.
  • Monitoring promotion performance across customers and channels.

Voucherify supports six basic promotion models 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 six 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 two 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 two 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 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.

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.


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.

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 – stores 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 amount.
  • 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 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 in real-time and further redemption attempts will fail. This feature works for built-in fields and 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, image URL, object. 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.


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) to customers: email, SMS, live chat, push notification, etc. 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 messages to all members at once.

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

  • Take 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. 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 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.

Accepting promotions

Now your customers have a promo code or saw a banner about a cart-level promotion and they 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 10 months 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.