How to use metadata (custom attributes) in Voucherify?

In this section:

  1. What is metadata?
  2. Standard and nested metadata
  3. Create metadata
  4. Campaign and voucher metadata
  5. Copying metadata between projects
  6. Build validation rules
  7. Target specific segments

What is metadata?

Metadata enables you to add custom data to Voucherify, which you can later use for building validation rules and reporting/tracking. Every object type like:

  • voucher
  • campaign
  • customer
  • product
  • SKU
  • redemption
  • publication
  • order
  • loyalty tier
  • promotion tier
can have some attributes that are not built-in by default, but you need them to customize promo campaigns. For example, you can add custom attributes to your customers and segment them accordingly to characteristics unique for your business model (e.g., base your customer segment on ice cream flavor preferences of your customers).
Moreover, metadata added to redemption object enables you to create limits for redemptions, which are not possible with built-in validation rules. For example, taxi companies very often offer promo codes for rides booked at particular hours, redemption metadata enables them to create redemption rules based on the time when the journey happens (redemption) and time when it was booked (custom metadata attribute).
There are plenty of use cases for metadata, and each of them is unique. They give you extreme flexibility and freedom in creating rules and limits for promotions and segmentation of your customers.
You can see some videos with metadata use cases here.

Standard and nested metadata

To extend the customization capabilities of Voucherify, you can also use nested metadata properties. If your business logic does not match any of the predefined Voucherify objects, you can create a new custom object. For example, you may create a new metadata Payment and add to it several nested properties, such as payment_method, payment_channel, or payment_tax. To customize these properties further, you can decide about the type of the given metadata property and optionally set different conditions, e.g., payment method has to be either credit card or wire transfer

Custom schema

Payment nested metadata

If you want to allow more than one value per metadata property to be available in the API, please check the "Is Array" box. 

Add metadata

Metadata Schema allows you to take care of the integrity of your metadata. This is achieved by enabling administrators to set a type of each metadata field and to define if it’s optional or not.

Only the Administrator can access and modify the validation scheme.

Let's see an example of the schema validator. We're going to add a custom field affiliate ID to all campaign and redemption objects in the project. This way, campaigns can have optional metadata of affiliate_ID, and redemptions invoked by them will also have proper metadata assigned. This way, you can easily track which affiliates bring in the most redemptions.

To start with, go to the project settings and find the Metadata section.

First, choose Voucherify objects to assign metadata. You can define properties for campaigns, vouchers, publications, redemptions, products, SKUs, customers, orders, and more. If those objects do not fit your promotional workflow, create custom metadata objects by visiting the Nested metadata section.

In order to start, click Add a new definition.

By allowing only defined properties, you will be able to send only predefined metadata in the API calls. New metadata added outside Metadata Schema (undefined) will not be allowed.


In the next step, define a property name and type. Let's use an affiliate_ID as a property assigned to the project's campaigns and redemptions. 

You can choose between several different property types:

Property types for metadata

Here, you can add some optional length constraints or even set a condition that the metadata property has to be an exact match to the value (or many custom values).

Affiliate ID metadata

You can unmark the checkbox to set each property as optional, not mandatory. Otherwise, it'll be treated as required.

When all campaigns' restrictions are in place, save your schema.

Now, let's define all redemptions invoked amongst this project by the same affiliate_ID. Just select the Redemption object and repeat the previous step of the tutorial.

Campaign and Voucher Metadata

You can add metadata to your vouchers and campaigns in the Campaign Manager. While in the Campaign Manager, you can select to either follow the campaign or voucher metadata schema. If you use the voucher metadata schema, the metadata will be validated against the voucher schema. This new functionality ensures that there are no conflicts between your campaign and voucher metadata schema which before have been used in parallel for the same object. 

If you use voucher metadata (set active by default), the set metadata will be copied for new vouchers during the voucher generation process (they will be assigned to both campaign and vouchers). On the other hand, if you uncheck this option, added metadata attributes will be assigned to the campaign but they will not be copied and assigned to codes metadata. 

Metadata voucher schema

Copying metadata between projects

You can use the Dashboard to quickly re-use metadata properties used throughout different projects. Instead of creating new Metadata Schema from scratch for a new project, you can now copy metadata definitions between projects. You can perform this action for both Standard and Nested metadata properties.

Copying metadata

Build validation rules

You can also use your metadata schema to build fine-grained validation rules that determine your desired redemption circumstances. 

if you want to learn more about validation rules, please visit this section

You can build your validation rules based on customer, product, order, and redemption metadata. For instance, you can decide that only orders made by Visa cards are eligible for a discount. 

Order metadata

Target customer segments

You can create a metadata validation schema for "customer" objects and use it for a later segmentation. By way of example, you can add a membership field to the schema and collect information about membership levels to offer different incentives for different members.

membership metadata

After adding this field, you'll be able to filter out your clients by using a membership field. Later on, you can easily create a segment with customers who meet the criteria defined by schema properties.

All you have to do is to name the new segment, select its criteria (confirm with Add) and save the segment. 

Customer segment based on metadata

Still need help? Contact Us Contact Us