Getting Started with Metadata

Custom attributes that are not built-in Voucherify can be added to your project as metadata. Metadata attribute is a set of key/value pairs that you can use to customize your campaigns. In this article, you'll learn how to create metadata attributes and use them to track, report, and personalize your promotions.
Visit our Developer Hub to learn how to manage metadata via the API.

In this article

  1. How metadata works
  2. Types of metadata
  3. How to add metadata
  4. How to use metadata
  5. Maintenance


How does metadata work?

Before you use metadata attributes in your promotions, you need to add them to the Metadata Schema. Go to the Project Settings and choose Metadata Schema.

 By expanding the list of Standard schemas from the menu on the right, you can see that every:

  • voucher
  • campaign
  • customer
  • product
  • SKU
  • redemption
  • publication
  • order
  • order item
  • loyalty tier
  • promotion tier
can be extended with metadata attributes.
Adding metadata to the Schema ensures data consistency across your projects. Attributes added to a particular schema are saved and can be reused every time you create a new Voucherify object. For example, if you add new attributes to the Customer schema, you'll be able to use them every time you create a new Customer profile or promotion rules. 

Types of metadata

Thanks to the multiple data types support, your metadata may represent a variety of different values:
  • Text
  • Number
  • Flag
  • Date
  • Date Time
  • Image URL
  • Object (creates nested metadata structure)

Text and Numbers

When adding text and number attributes, you can use additional criteria for their values. 

Text:

  • has a minimum length of
  • has a maximum length of
  • has an exact length of
  • is equal to any of

Number:

  • is less than
  • is less than or equal
  • is greater than or equal
  • is equal to any of
  • is not equal to any of
  • is greater than

Flag (Boolean)

Metadata of the flag type can take the value of true or false. 

Date and Date Time

Dates and time in Voucherify are consistent with the ISO 8601 norms. If you'd like to add metadata with dates or time using the API, remember to follow the required format. Here's an example of the correct date-time value: 2020-03-11T09:00:00.000Z.

Object

Objects enable you to group attributes and create nested schemas. Each object can gather many single metadata properties. You'll learn how to use objects in the Nested Metadata section. 


How to define metadata attribute

First, decide if you want to add single metadata properties or create a nested metadata structure.

Standard Metadata

To add a single metadata attribute, choose the Standard list schema, and click Add new definition.

Add the Name (key) of your attribute and choose the Type

' Is Array' checkbox comes in handy when you want to assign more than one value to the attribute. 

Example of array metadata attribute:

With the Mandatory checkbox, you can decide whether adding attribute value will be required while creating new resources in Voucherify. For example, if a new attribute in the Customer Schema is set to mandatory, you'll need to add this attribute and define its value every time you pass a new customer record to the application.

Nested Metadata

Besides standard metadata properties, you can create an object type attribute and use it to nest other attributes inside. For example, you may create a new metadata Payment and add to it several nested properties, such as payment_method, payment_channel, payment_tax.

First, add a new custom schema with the Plus.

Add a name and confirm with Create. In the schema, use Add new definition to create attributes you'd like to nest.

When ready, you can attach the custom schema to the object type attribute in the Standard schema. In the picture below, you can see the standard order schema with Payment attribute (object) that nests properties added to custom payment schema (payment_tax, payment_method).

After saving the schema, order metadata can nest payment information.


How to Use Metadata

Metadata extends the customization capabilities of Voucherify. Properties added to vouchers and campaigns help you to better track and report your results. Attributes used to build customer segments and validation rules provide custom promotion limits and campaign workflows.

Tracking and reporting 

Metadata can represent properties useful for tracking your results and introducing ongoing boosts. You can export your data from Voucherify to analyze them or build integration with BI tools to provide data sync. All your redemptions, customers, and vouchers can be downloaded in a CSV file from your dashboard. 

Customers

Metadata added to Customer Schema extends basic attributes assigned to each customer in Voucherify. In this way, Voucherify can reflect your CRM data structure. Each metadata attribute can later serve as a redemption limit or filter in the segmentation of your audience. Go here to learn more.

Products

By using metadata, you can create product-specific promotion rules without uploading your product catalog to Voucherify. Metadata added to cart items are validated while redeeming the code to check if a customer qualifies for a promotion. You can also add your products to Voucherify and use metadata to extend products characteristic. Likewise, each product metadata can model redemption limits and promotion rules. Go here to read more. 

Validation Rules

You can use metadata schemas to build fine-grained validation rules that determine your desired redemption circumstances. Rules builder creates limits on customerproduct, order, and redemption metadata. 


Maintenance 

To maintain metadata in your projects easily, we recommend always add metadata to the schema before using it in your campaigns. As an Administrator, you can enforce such behavior by enabling the option "Allow only defined properties" in each schema. 

Note that only the Administrator of your account can modify metadata in schemas. You can add and remove metadata definitions. All removed properties will be stored in the Removed definitions if you'd like to restore them in the schema.

Using the bin icon next to the removed definition forces purging metadata definition from your existing resources. Purging metadata definition is an asynchronous operation and it takes time to be executed. You will be notified once it's done in the notifications center in your dashboard. 

Copy Metadata Schema between Projects

You can quickly copy and re-use metadata properties added throughout different projects. You can perform this action for both Standard and Nested metadata schemas.

Copying metadata

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us