Skip to main content

​
What is metadata

Metadata in Voucherify is custom key–value data you add to objects (customers, orders, products, campaigns) to control targeting, personalize incentives, and improve tracking and reporting. Examples:
  • 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
To learn more about metadata, see the Metadata mapping article.

​
How metadata works

Before using metadata attributes, you must add them to the Metadata schema in Project settings.

​
Supported objects

You can extend the following entities with metadata:
  • Voucher
  • Campaign
  • Customer
  • Product
  • Redemption
  • Publication
  • Order
  • Order line item
  • Loyalty tier
  • Promotion tier
  • Earning rule
  • Reward

​
Schema limits

Each schema (e.g., customer or campaign) can contain up to 100 definitions.
Removed definitions still count toward the 100-definition limit. You must purge them to free up space.
Nested metadata counts as one definition, but individual nested components are counted separately.

​
Metadata types

You can define metadata using the following data types:
TypeDetails
StringSupports criteria: min/max/exact length, equal to any of.
NumberSupports criteria: less/greater than (or equal), equal to any of, not equal to.
FlagBoolean values (true or false).
Date / Date timeComplies with ISO 8601 (e.g., 2020-03-11T09:00:00.000Z).
Image URLRepresents image’s URL.
ObjectGroups attributes to create nested structures.
GeopointRepresents location. Stores coordinates as latitude, longitude.

​
Define a new metadata attribute

To use metadata on resources (for example, customers or vouchers), you first define it in the Metadata schema. A definition describes the metadata key, its type, and whether it is optional or required.
Be careful when you mark metadata as required.If you make many fields required and you do not send them in your payload, Voucherify rejects the request with a validation error.
1

Open the new metadata form

Open Metadata schema, then select the ⋮ at the end of the object line and select “Add definition”. Optionally, you can click on the object name and select “Create” in the new window pop up.
The definition you create is added to the schema in Project settings.
2

Enter the metadata key (property name)

In Property name (key), type the name of your metadata field.
Property name (key) is required. You cannot save the definition if this field is empty.
3

Choose whether the property is required

Use the dropdown next to is a(n) to mark the metadata as:
  • optional, or
  • required
If a metadata field is required, you must provide it when creating a new resource of this object type.
4

Choose if the property holds a single value or multiple values

Use the dropdown next to property containing to choose:
  • single (one value), or
  • multiple (an array of values)
If you choose multiple, the stored value becomes a list of values for the same key.
5

Select the metadata type

Use the Type dropdown to select the value type:
  • String
  • Number
  • Date
  • Datetime
  • Flag
  • Image URL
  • Geopoint (enterprise feature, on demand)
The selected type controls which validation rules you can define below.
6

Properties (optional)

You can add properties for the metadata value. For example, for text fields you can set:
  • minimum length
  • maximum length
  • exact length
  • allowed values (equal to any of)
Some properties show input fields where you enter numeric limits or allowed values.
7

Save the definition

Select Save to add the metadata definition to the schema.

​
Nested metadata

In addition to standard metadata properties, you can create an Object type attribute and use it to group other metadata fields under one key. For example, you can create a metadata property called Payment and add nested properties such as:
  • payment_method
  • payment_channel
  • payment_tax
1

Create a nested schema

Select Create nested schema at the top of the page.Enter a name for the nested schema (for example, Payment).
2

Add nested metadata definitions

Inside the nested schema, add metadata definitions the same way you do for standard metadata.
3

Attach the nested schema to an Object attribute

In the Standard schema, create (or open) a metadata definition with type Object.Attach your nested schema to this Object attribute.
4

Save the schema

Save your changes.
After saving, you can store nested metadata values under the parent key (for example, payment information inside Payment).

​
Unknown metadata

Unknown metadata is custom data sent to Voucherify without a definition in the Metadata Schema.
  • Format: Always treated as a string.
  • Limitations: Limited filtering and validation compared to defined metadata.
  • Source: Created via API requests, CDP imports, or manual entry of undefined properties.

​
Maintenance

To maintain metadata in a project, we recommend always adding metadata to the schema before using it in your campaigns.

​
Validation modes

  • Allow only defined metadata: Rejects requests (400 Bad Request) if they contain undefined metadata fields.
  • Allow any metadata: Accepts undefined fields but still validates defined fields against the schema.

​
Remove, restore, and purge

  • Remove: Moves the definition to the “Removed definitions” section.
  • Restore: Returns a removed definition to the active schema.
  • Purge: Permanently removes the definition from all existing resources. This is an asynchronous process.

​
Copying schema

You can copy definitions from another project:
1

Open Settings

Go to Project settings > Metadata schema.
2

Start Copy

Select the option to copy from another project.
3

Select Definitions

Choose the source project and the specific definitions to import.

​
Technical implementation

When interacting with the API, you send metadata as a JSON object. The example below shows a request (the data you send to Voucherify) and the resulting response (the confirmation sent back by the system). 
{
  "name": "Summer Promotion",
  "metadata": {
    "region": "West_Coast",
    "is_priority": true,
    "membership_duration": 12
  }
}