Update Metadata Schema

curl --request PUT \
  --url https://{cluster}.voucherify.io/management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId} \
  --header 'Content-Type: application/json' \
  --header 'X-Management-Id: <api-key>' \
  --header 'X-Management-Token: <api-key>' \
  --data '
{
  "properties": {},
  "allow_defined_only": true
}
'

{
  "id": "ms_u3bIQLbdU0fi3rhqpTLiF26T",
  "related_object": "reward",
  "properties": {
    "region": {
      "type": "string",
      "array": true,
      "optional": false,
      "object_type": null,
      "eq": [
        "EMEA",
        "APAC",
        "LATAM",
        "NA"
      ]
    }
  },
  "allow_defined_only": null,
  "created_at": "2024-04-29T12:03:55.991Z",
  "updated_at": null,
  "object": "metadata_schema"
}

Update Metadata Schema

Updates a metadata schema.

With this request, you can:

Add a nonexistent attribute definition to the metadata schema.
Update an existing attribute definition by overwriting its current values.

In the request, you can provide only those definitions you want to add or update. Definitions omitted in the request remain unchanged.

However, if you want to update a definition, you will have to add all its current key-value pairs as well. Only the pairs sent in the request are saved for this definition. This means that the key-value pairs that are not sent in a request are restored to default values. For example, if your definition has an array with values and it is not sent in an update request, the array values will be deleted.

👍 Additional Notes

You cannot change the type of an existing schema, e.g. from "string" to "number".

You can remove a definition with this endpoint by providing "deleted": true in the request. It will be moved to the Removed definitions section in the user interface. However, you cannot permanently remove a definition with this endpoint.

📘 Metadata Documentation

Read the Getting Started with Metadata and Metadata Mapping articles to learn how metadata work in Voucherify.

PUT

management

projects

{projectId}

metadata-schemas

{metadataSchemaId}

Update Metadata Schema

curl --request PUT \
  --url https://{cluster}.voucherify.io/management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId} \
  --header 'Content-Type: application/json' \
  --header 'X-Management-Id: <api-key>' \
  --header 'X-Management-Token: <api-key>' \
  --data '
{
  "properties": {},
  "allow_defined_only": true
}
'

{
  "id": "ms_u3bIQLbdU0fi3rhqpTLiF26T",
  "related_object": "reward",
  "properties": {
    "region": {
      "type": "string",
      "array": true,
      "optional": false,
      "object_type": null,
      "eq": [
        "EMEA",
        "APAC",
        "LATAM",
        "NA"
      ]
    }
  },
  "allow_defined_only": null,
  "created_at": "2024-04-29T12:03:55.991Z",
  "updated_at": null,
  "object": "metadata_schema"
}

Authorizations

X-Management-Id

string

header

required

X-Management-Token

string

header

required

Path Parameters

projectId

string

required

Provide the unique identifier of the project.

Example:

"proj_TrlkLiH4"

metadataSchemaId

string

required

Provide the unique identifier of the metadata schema.

Example:

"ms_f0r4hm3ta6a4a5ch3ma"

Body

application/json

Defines the metadata schema to be updated.

properties

object

required

Contains metadata definitions. There can be many properties within this object.

Only the properties sent in the request will be updated. However, if you send a property, all its key-value pairs must be provided - otherwise, they will be overwritten to new values.

You cannot change the "type" property. However, it is required, so you need to add it to the request.

Show child attributes

properties.{key}

Metadata Definitions · object

Custom definition name. This is also shown in Project Settings > Metadata Schema in the Voucherify Dashboard.

Show child attributes

properties.{key}.type

enum<string>

required

Indicates the type of metadata. Note that "geopoint" type is a paid feature.

Available options:

string,

number,

object,

date,

datetime,

geopoint,

boolean,

image_url

properties.{key}.optional

boolean

required

Indicates if this definition is optional or not for the resource.

properties.{key}.array

boolean

required

Indicates if the definition is an array.

properties.{key}.deleted

boolean

Indicates if the definition has been deleted from the schema.

properties.{key}.object_type

string | null

The name of the custom resource (i.e. a nested object) if the resource has been previously defined. Otherwise, it is null for other types.

properties.{key}.min_length

integer

Value indicating the minimum length. Available only for the string type.

properties.{key}.max_length

integer

Value indicating the maximum length. Available only for the string type.

properties.{key}.exact_length

integer

Value indicating the exact length. Available only for the string type.

properties.{key}.eq

(number | string)[]

Array of values that are allowed. Available only for the string and number types.

Adds numbers to the array. The value should be up to two decimal places.

properties.{key}.ne

number[]

Array of values that are not allowed. Available only for the number type.

Adds number to the array. The value should be up to two decimal places.

properties.{key}.lt

number

A property of the number type must have less than this value. The value should be up to two decimal places.

properties.{key}.lte

number

A property of the number type must be less than or equal to this value. The value should be up to two decimal places.

properties.{key}.gt

number

A property of number type must be greater than this value. The value should be up to two decimal places.

properties.{key}.gte

number

A property of number type must be greater than or equal to this value. The value should be up to two decimal places.

allow_defined_only

boolean

Restricts the creation of metadata fields when set to true. In other words, it indicates whether or not you are allowed to create new metadata definitions; for example, in the campaign manager or publication manager. If it is set to true, then only the defined fields will be available for assigning values.

Response

Returns the details about the updated metadata schema.

Response body schema for PUT management/v1/projects/{projectId}/metadata-schemas/{metadataSchemaId}. Object representing a metadata schema.

string

required

Unique identifier of the metadata schema.

The resource type. You can define custom metadata schemas, which have a custom "related_object" resource type. The standard metadata schemas are: "campaign", "customer", "earning_rule", "loyalty_tier", "order", "order_item", "product", "promotion_tier", "publication", "redemption", "reward", "voucher".

properties

object

required

Contains metadata definitions.

Show child attributes

properties.{key}

Metadata Definitions · object

Custom definition name. This is also shown in Project Settings > Metadata Schema in the Voucherify Dashboard.

Show child attributes

properties.{key}.type

enum<string>

required

Indicates the type of metadata. Note that "geopoint" type is a paid feature.

Available options:

string,

number,

object,

date,

datetime,

geopoint,

boolean,

image_url

properties.{key}.optional

boolean

required

Indicates if this definition is optional or not for the resource.

properties.{key}.array

boolean

required

Indicates if the definition is an array.

properties.{key}.deleted

boolean

Indicates if the definition has been deleted from the schema.

properties.{key}.object_type

string | null

The name of the custom resource (i.e. a nested object) if the resource has been previously defined. Otherwise, it is null for other types.

properties.{key}.min_length

integer

Value indicating the minimum length. Available only for the string type.

properties.{key}.max_length

integer

Value indicating the maximum length. Available only for the string type.

properties.{key}.exact_length

integer

Value indicating the exact length. Available only for the string type.

properties.{key}.eq

(number | string)[]

Array of values that are allowed. Available only for the string and number types.

Adds numbers to the array. The value should be up to two decimal places.

properties.{key}.ne

number[]

Array of values that are not allowed. Available only for the number type.

Adds number to the array. The value should be up to two decimal places.

properties.{key}.lt

number

A property of the number type must have less than this value. The value should be up to two decimal places.

properties.{key}.lte

number

A property of the number type must be less than or equal to this value. The value should be up to two decimal places.

properties.{key}.gt

number

A property of number type must be greater than this value. The value should be up to two decimal places.

properties.{key}.gte

number

A property of number type must be greater than or equal to this value. The value should be up to two decimal places.

allow_defined_only

boolean | null

required

Restricts the creation of metadata fields when set to true. It indicates whether or not you can create new metadata definitions, e.g. in the campaign or publication manager. If set to true, then only the defined fields are available for assigning values.

created_at

string<date-time>

required

Timestamp representing the date and time when the metadata schema was created. The value for this parameter is shown in the ISO 8601 format.

Example:

"2021-12-03T13:33:44.556Z"

updated_at

string<date-time> | null

required

Timestamp representing the date and time when the metadata schema was updated. The value for this parameter is shown in the ISO 8601 format.

Example:

"2022-08-11T08:05:30.695Z"

object

string

default:metadata_schema

required

The type of the object represented by the JSON. This object stores information about the metadata schema.

Get Metadata Schema Delete Metadata Schema

⌘I

Introduction

Endpoints

Events

Update Metadata Schema

Authorizations

Path Parameters

Body

Response