> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voucherify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata

> Learn how to add custom attributes to your objects using metadata schema and how to manage them

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.

<Accordion title="Metadata examples">
  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.

  <Note>
    <Badge color="blue">Technical details</Badge>

    In the Voucherify API, metadata are handled as JSON key-value pairs.
  </Note>
</Accordion>

## How metadata works

You can attach metadata to the following Voucherify resources.

<Accordion title="Supported resources in metadata">
  Voucherify resources with metadata:

  * Voucher
  * Campaign
  * Customer
  * Product
  * Redemption
  * Publication
  * Order
  * Order line item
  * Loyalty tier
  * Promotion tier
  * Earning rule
  * Reward
</Accordion>

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.

<Accordion title="Nested metadata example">
  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.
</Accordion>

## 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**).
* **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

<Info>
  <Badge color="gray">Metadata definition permissions</Badge>

  Only users with the **Admin** role and the **Add and modify Metadata schema** permission can add, edit, and manage metadata schemas.
</Info>

<Tip>
  To maintain data consistency, always add metadata to the schema before using it in your resources.
</Tip>

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.

<Steps>
  <Step title="Open new metadata form">
    In a given resource, **Create** the schema to define new metadata.
  </Step>

  <Step title="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**

    <Info>
      <Badge color="gray">Required metadata: Definitions and requests</Badge>

      If 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.
    </Info>

    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.
  </Step>

  <Step title="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)

    <Info>
      The selected type controls which <Tooltip headline="Validation rule" tip="Validation rules help you limit the application of incentives for better targeting." cta="Read Validation rule guide" href="/optimize/validation-rules-reference">validation rules</Tooltip> you can define. Some metadata types can't be used in validation rules, for example **geopoint**.
    </Info>
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the definition">
    Once ready, **Save** to add the metadata definition to the schema.
  </Step>
</Steps>

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**.

<Steps>
  <Step title="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.
  </Step>

  <Step title="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](#define-new-metadata-schema).

    Add as many metadata schemas as needed.
  </Step>

  <Step title="Finish the nested metadata">
    Once you've added all metadata schemas to the nested metadata, close the detailed view.
  </Step>
</Steps>

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.

<Tip>
  <Badge color="green">Use unknown metadata to create new definition</Badge>

  To 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**.
</Tip>

## 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.

  <Warning>
    **Removed definitions** still count toward the 100-definition limit. **Purge** a definition to free up space.
  </Warning>
* **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.

  <Info>
    Metadata purge is **not** available for:

    * Earning rule
    * Publication
    * Redemption
    * Reward
  </Info>
* **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**.

<Danger>
  <Badge color="red">Irreversible actions</Badge>

  Both **Purge** and **Clear schema** can't be reversed. Make sure you really want to perform these actions!
</Danger>

### Copy schema from another project

You can copy metadata schema definitions from another project into your current project.

Go to **Project settings** > **Metadata schema**.

<Steps>
  <Step title="Copy schema from project">
    Select the **Source project** from which you want to copy schema.
  </Step>

  <Step title="Select definitions">
    Select the **Schema** to copy. You can select **Standard** or **Nested** schema definitions.

    Confirm with **Copy**.
  </Step>
</Steps>

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.

## Related features

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.

<AccordionGroup>
  <Accordion title="Metadata in customers">
    Metadata added to the **Customer** schema extends basic attributes assigned to each [customer](/prepare/customers) 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](/prepare/customer-segments) your audience.
  </Accordion>

  <Accordion title="Metadata in 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](/prepare/products) to Voucherify and use metadata to extend product characteristics. Likewise, each product metadata can model redemption limits and promotion rules.
  </Accordion>

  <Accordion title="Metadata in validation rules">
    You can use metadata schemas to build fine-grained [validation rules](/optimize/validation-rules-reference) that determine your desired redemption circumstances. The validation rule builder can create limits on customer, product, order, and redemption metadata.

    <Note>
      Some metadata types, like **geopoint**, can't be used to create a validation rule.
    </Note>
  </Accordion>
</AccordionGroup>