---
title: "Create Metadata Schema"
method: POST
path: "/management/v1/projects/{projectId}/metadata-schemas"
tags: ["Management"]
---

# Create Metadata Schema

`POST /management/v1/projects/{projectId}/metadata-schemas`

Creates a new metadata (custom attribute) schema for a given resource.

The schema consists of a set of key-value pairs to customize Voucherify resources. 

You can nest your object within a standard metadata schema, e.g. within a campaign or customer schema. However, your nested object can't include another nested object. The standard metadata schemas are:
- Campaign
- Voucher
- Publication
- Redemption
- Product
- Customer
- Order
- Order line item
- Loyalty Tier
- Promotion Tier
- Earning rule
- Reward

Use this endpoint to define a metadata schema of a given resource for the first time. Once you configure a metadata schema for a given `related_object`, use the PUT [Update metadata schema](/api-reference/management/update-metadata-schema) endpoint to either update or add new metadata key-value pairs. For example, use this endpoint to define a metadata schema for `related_object: campaign` for the first time. If you want define a new metadata property for `campaign`, use the [PUT Update metadata schema](/api-reference/management/update-metadata-schema) endpoint.

> 📘 Metadata Documentation
>
> Read [the Getting Started with Metadata](/prepare/metadata) and [Metadata Mapping](/guides/metadata-mapping) articles to learn how metadata work in Voucherify.

## Request body

- ManagementProjectsMetadataSchemasCreateRequestBody
  - `related_object` string, required — The resource type. You can define custom metadata schemas, which have a custom `"related_object"` resource type, or you can use standard resource types: `"campaign"`, `"customer"`, `"earning_rule"`, `"loyalty_tier"`, `"order"`, `"order_item"`, `"product"`, `"promotion_tier"`, `"publication"`, `"redemption"`, `"reward"`, `"voucher"`.
  - `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.
  - `properties` object, required — Contains metadata definitions. There can be many properties within this object. Only the properties sent in the request will be created.

## Response `200`

Returns the details about the metadata schema.

- ManagementProjectsMetadataSchemasCreateResponseBody — Object representing a metadata schema.
  - `id` string, required — Unique identifier of the metadata schema.
  - `related_object` string, required — 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.
  - `allow_defined_only` boolean, nullable, 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.
  - `updated_at` string, date-time, nullable, 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.
  - `object` string, required — The type of the object represented by the JSON. This object stores information about the metadata schema.

## Other responses

- `400` — Returns an error if the payload has incorrect values.
- `401` — Returns an error if an invalid token was provided.
- `402` — Returns an error if the current plan does not include the Management API feature.
- `404` — Returns an error when a resource could not be found.
- `409` — Returns an error if the resource has a duplicate.

---

[API](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions.md) · [All operations](https://skmtc.net/voucherifyio/apis/voucherify-api-async-actions/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/voucherifyio/voucherify-api-async-actions/revisions/4982266e0494/schema)