Skip to main content
Metadata (custom attributes) extends the customization capabilities of Voucherify. In addition to standard Voucherify configuration fields, metadata allow you to create custom key–value data. This way, you can add more attributes to objects (customers, orders, products, campaigns, and more) to optimize, personalize, and track incentives.
See what kind of metadata you can combine with Voucherify resources:
  • Customer: loyalty_tier: gold, lifetime_value: 1200
  • Order: cart_value: 85, contains_subscription: true
  • Product: category: skincare, margin_band: high
  • Campaign: customer_group: A, objective: repurchase
Metadata can be viewed in the details of a given resource.
Technical detailsIn the Voucherify API, metadata are handled as JSON key-value pairs.

​
How metadata works

You can attach metadata to the following Voucherify resources.
Voucherify resources with metadata:
  • Voucher
  • Campaign
  • Customer
  • Product
  • Redemption
  • Publication
  • Order
  • Order line item
  • Loyalty tier
  • Promotion tier
  • Earning rule
  • Reward
Before using metadata attributes, it’s recommended to add them to the Metadata schema in Project settings. When added, you can easily reuse your custom attributes and ensure they are consistently applied. Each resource can contain up to 100 definitions. You can also create metadata objects as nested metadata. Nested metadata can group other metadata with different types to be used as one custom attribute in a Voucherify resource. Nested metadata counts as one definition in a given resource (for example, in Customer). However, a nested metadata schema is also limited up to 100 definitions.
You can create a metadata property called Payment and add nested properties such as:
  • payment_method with a string type,
  • payment_channel with a string type,
  • payment_tax with a number type,
  • payment_deferred with a flag type.
The Payment nested metadata can be then added, for example, to the Product resource as an Object type metadata definition.

​
Metadata types

You can define metadata using the following data types:
  • String: Supports properties – min./max./exact length, is equal to any of.
  • Number: Supports properties – less/greater than (or equal), is equal to any of, is not equal to.
  • Flag: Boolean values (true or false). In the API, this type is called boolean (see Metadata Schema Object).
  • Date and Date time: Complies with ISO 8601 (for example, 2020-03-11T09:00:00.000Z).
  • Image URL: Represents an image URL.
  • Object: Uses nested metadata, which groups several custom attributes under one object.
  • Geopoint (enterprise feature, on demand): Represents location. Stores coordinates as latitude, longitude, for example “37.786971, -122.399677”. Only available for customers and products.

​
Define new metadata schema

Metadata definition permissionsOnly users with the Admin role and the Add and modify Metadata schema permission can add, edit, and manage metadata schemas.
To maintain data consistency, always add metadata to the schema before using it in your resources.
A metadata schema definition determines the metadata key, its type, whether it is optional or required, and other properties. Go to Project settings > Metadata schema to define a new schema for a selected resource.
1

Open new metadata form

In a given resource, Create the schema to define new metadata.
2

Define metadata details

In Property name (key), type the name of your metadata field.Use the drop-down next to is a(n) to mark the metadata as:
  • optional
  • required
Required metadata: Definitions and requestsIf a metadata field is required, you must provide it when creating a new resource of this object type.If you do not include required metadata when sending a request, Voucherify rejects it with a validation error.
Use the drop-down next to property containing to choose:
  • single (one value)
  • multiple (an array of values)
If you choose multiple, the stored value becomes a list of values for the same key.
3

Select the metadata type

Use the Type drop-down to select the value type:
  • String
  • Number
  • Date
  • Datetime
  • Flag
  • Image URL
  • Object (nested metadata)
  • Geopoint (enterprise feature)
The selected type controls which you can define. Some metadata types can’t be used in validation rules, for example geopoint.
4

Properties (optional)

You can add properties, like is equal to any of, for the metadata value. You can set properties for strings, numbers, and objects.The metadata value then must meet the defined properties.
5

Save the definition

Once ready, Save to add the metadata definition to the schema.
The metadata definition is added to the Definitions list and can be used in a given resource.

​
Define nested metadata schema

Nested metadata are used as Object type attribute and they are used to group other metadata fields under one key. Go to Project settings > Metadata schema to Create nested schema.
1

Name the nested metadata schema object

In the pop-up screen, name your nested metadata schema and Save it to open its detailed view.When saved, your nested metadata schema object is added to the Nested metadata list.
2

Define metadata for the nested metadata object

In the nested metadata schema details, Create new metadata schema. Create your new metadata like in Define new metadata schema.Add as many metadata schemas as needed.
3

Finish the nested metadata

Once you’ve added all metadata schemas to the nested metadata, close the detailed view.
Nested metadata are listed in Metadata schema > Nested tab.

​
Unknown metadata

You can find the Unknown metadata tab in the detailed view of every resource. Unknown metadata is custom data sent to Voucherify without a definition in the Metadata schema. Unknown metadata:
  • Are always treated as a string.
  • Have limited filtering and validation compared to defined metadata. You have to type their key and value in the Unknown metadata filter.
  • Are usually created through API requests, CDP imports, or manual entry of undefined properties.
You can use unknown metadata to attach temporary or one-time custom attributes to resources without the need to define a schema first. Unknown metadata is helpful for cases such as marking a specific group for a campaign or adding unique attributes to a single product or voucher.
Use unknown metadata to create new definitionTo use unknown metadata and create new metadata definition, Edit the unknown metadata to open the metadata definition pop-up screen.There, you can edit property name, define if it’s optional or required and if it contains a single value or multiple values of a given Type.

​
Maintenance

Once you’ve added metadata definitions to schemas, you can manage them in the detailed view of a given resource. Go to Project settings > Metadata schema and select a given resource to open its detailed view.

​
Metadata validation modes

Metadata can be validated by Voucherify as follows:
  • Allow any metadata (default): Accepts undefined fields, but Voucherify still validates defined fields against the schema. For example, Voucherify rejects metadata that has a different type, disallowed values, or properties that don’t meet the defined schema.
  • Allow only defined metadata: Rejects requests if they contain undefined metadata fields or metadata doesn’t meet its definition.

​
Manage metadata schemas

In the metadata schema, you can:
  • Edit: Change metadata definition. However, you can’t change its Type.
  • Remove: Move the definition to the Removed definitions tab.
    Removed definitions still count toward the 100-definition limit. Purge a definition to free up space.
  • Restore: Return a removed definition to the active schema under Definitions tab.
  • Purge: Permanently remove the definition from the Removed definitions list and from all existing resources (for example removes the “VIP” flag from all customers). This is an asynchronous process that may take time to complete.
    Metadata purge is not available for:
    • Earning rule
    • Publication
    • Redemption
    • Reward
  • Clear schema: Completely delete the schema and its Definitions, Unknown definitions, and Removed definitions. However, this action does not Purge the metadata from relevant resources. If you want to also remove metadata from associated resources, first Purge then Clear schema.
Irreversible actionsBoth Purge and Clear schema can’t be reversed. Make sure you really want to perform these actions!

​
Copy schema from another project

You can copy metadata schema definitions from another project into your current project. Go to Project settings > Metadata schema.
1

Copy schema from project

Select the Source project from which you want to copy schema.
2

Select definitions

Select the Schema to copy. You can select Standard or Nested schema definitions.Confirm with Copy.
All defined metadata schema are added to the definition in the current project.

​
Use metadata in Voucherify

When you add metadata to your resources, like campaign or customer, you can either:
  • Use an existing metadata schema. This is a schema that’s defined in Project settings.
  • Add unknown property: Metadata that isn’t defined and won’t be added to the schema. It will be listed as an Unknown definition with a string type.
  • Add to schema: Define new metadata schema. Once saved, the metadata is added to the Definitions of a given resource.
When adding a metadata value to a resource, you can use the following Value types:
  • Undefined: The metadata is not added to the resource.
  • Null: The metadata is added to the resource, but its value is empty (set to null).
  • Value: Add value that meets the schema definition – its type and other properties.
Experiment with other features to improve your incentive optimization. You can use metadata with many different resources. Check some basic use scenarios below to get inspired.
Metadata added to the 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.
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 product characteristics. Likewise, each product metadata can model redemption limits and promotion rules.
You can use metadata schemas to build fine-grained validation rules that determine your desired redemption circumstances. The validation rule builder can create limits on customer, product, order, and redemption metadata.
Some metadata types, like geopoint, can’t be used to create a validation rule.
Last modified on July 27, 2026