Getting Started with Metadata

Contents

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, you need to add them to the Metadata Schema. Go to the Project Settings and choose Metadata Schema.

You can see that every:

can be extended with metadata attributes. Adding metadata to the Schema ensures data consistency across 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.

Metadata

• Text
• Number
• Flag
• Date
• Date Time
• Image URL
• Object (creates nested metadata structure)
• Geopoint

Text and Numbers

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

Flag (Boolean)

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

Date and Date Time

Dates and times in Voucherify comply with ISO 8601 norms. If you would like to add metadata with dates or times using the API, remember to follow the required format. Here is 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. 

Geopoint

Geopoint represents the customer's location. You can use it to build area-specific validation rules and introduce geofencing to your campaigns. This type of metadata stores location using coordinates in order: latitude, longitude, where allowed values for both are as follows:

• latitude from -90 to 90,
• longitude from -180 to 180

How to define a metadata attribute?

In Project settings, you can define single metadata properties or create a nested metadata structure.

To create standard metadata, go to the Metadata schema page, which contains a list of objects like Campaign, Voucher, Publication, and more. You can add a metadata definition by:

• clicking the three dots next to the object and selecting Add definition
• clicking directly on the object name to open its schema and clicking Create

In the window, fill in the metadata details such as the property name, whether it’s required or optional, if it accepts single or multiple values, and the data type, like string, number, date, etc.

The multiple option is useful to assign more than one value to the attribute. This creates an array of values for the key.

With the required option, you can decide whether adding an attribute value is required while creating new resources in Voucherify. For example, if a “region” metadata attribute is set to mandatory in the Customer schema, you need to add it and define its value every time you pass a new customer record to Voucherify.

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

Click the Create nested schema button at the top. Enter the name for the nested schema. Inside the nested schema, you can add metadata definitions just like for standard metadata.

When ready, you can attach the nested schema to the object type attribute in the Standard schema.

After saving the schema, metadata can nest payment information.

Unknown metadata is custom data sent to Voucherify without a predefined data type or explicit assignment in the Metadata schema. It is always treated as a string with limited filtering and validation capabilities.

Unknown metadata can be generated when:

• An API request includes metadata not defined in the Metadata Schema.
• A new custom property is enabled in a CDP.
• A user manually adds metadata during object creation (e.g., a customer, product, or voucher).
• Metadata is imported via a file with previously undefined properties.
• "Other" metadata is selected when creating a validation rule.

Unknown metadata allows users to attach temporary or one-time custom data to objects without prior schema definition. It is helpful for cases such as marking a specific group for a campaign or adding unique attributes to a single product or voucher. However, since it lacks a predefined type, it can’t be used for advanced filtering and validation like defined metadata.

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. Metadata configurations are applied to entities based on their definitions in Project settings. The appropriate value type should be chosen based on the intended semantics of the metadata field .Metadata in the system can have three distinct value types: While both Undefined and Null indicate the absence of a standard value, they serve different purposes: 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, orders, and vouchers can be downloaded from your dashboard in a CSV file. 

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 segmenting 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 is 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' characteristics. 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 customer, product, order, and redemption metadata.

Maintenance 

To maintain metadata in a project, we recommend always adding 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 metadata in each schema. 

When Allow only defined metadata is set on, the payload must contain only metadata fields that are explicitly defined in the metadata schema. If the payload includes any undefined metadata fields, the request will be rejected with a 400 Bad Request error.

When Allow any metadata is set on, the payload can include undefined metadata fields, which will be stored separately in an “undefined” section. However, all defined metadata fields must still comply with the schema. If any defined field is missing or contains an invalid value, the request will return a 400 Bad Request error.

You can also remove metadata definitions. All removed properties are stored in the Removed definitions. Removed definitions can be restored back to the schema or purged.

Click Purge to force complete removal of a 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. 

• campaigns
• loyalty tiers
• order items
• orders
• promotion tiers
• customers
• products
• vouchers

You can also clear the schema. This action removes all definitions, unknown definitions, and removed definitions. This action can't be reversed.

Copy Metadata from another project

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.