# Create a metafield definition > Declare a new custom field on an owner type. {/* generated:versioned-pages - edit _pm-authored, not this file */} `POST /api/metafield_definitions` Creates a MetafieldDefinition resource. Declares a custom field. Give it a `namespace` and `key` (which together identify it), the `ownerType` it applies to, the `type` of data it holds, and optionally `validations`. Once created, you can set [Metafield](/api/product-management/metafields/) values for it on records of that owner type. ## Request body | Property | Type | Required | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `constraints` | `EmbeddedMetafieldDefinitionConstraintResource[]` | - | The constraint rules scoping where this metafield definition applies (e.g. by category or channel). | | `description` | `string \| null` | - | | | `key` | `string` | - | | | `name` | `string` | - | | | `namespace` | `string` | - | | | `ownerType` | `"/api/metafield_owner_types/products" \| "/api/metafield_owner_types/collections" \| "/api/metafield_owner_types/variants" \| "/api/metafield_owner_types/sale_offers" \| "/api/metafield_owner_types/purchase_offers"` | Yes | | | `type` | `"/api/metafield_definition_types/single_line_text_field" \| "/api/metafield_definition_types/multi_line_text_field" \| "/api/metafield_definition_types/number_integer" \| "/api/metafield_definition_types/number_decimal" \| "/api/metafield_definition_types/json" \| "/api/metafield_definition_types/list__single_line_text_field" \| "/api/metafield_definition_types/list__number_integer" \| "/api/metafield_definition_types/list__number_decimal" \| "/api/metafield_definition_types/list__product_reference" \| "/api/metafield_definition_types/list__media_reference" \| "/api/metafield_definition_types/product_reference" \| "/api/metafield_definition_types/media_reference" \| "/api/metafield_definition_types/metaobject_reference" \| "/api/metafield_definition_types/list__metaobject_reference"` | Yes | | | `validations` | `EmbeddedMetafieldDefinitionValidationResource[]` | - | The validation rules applied to the values of metafields using this definition. | ## Response **201** - MetafieldDefinition resource created | Property | Type | Required | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `@context` | `string \| object` | - | | | `@id` | `string` | Yes | | | `@type` | `string` | Yes | | | `constraints` | `EmbeddedMetafieldDefinitionConstraintResource[]` | - | The constraint rules scoping where this metafield definition applies (e.g. by category or channel). | | `createdAt` | `string` | - | The date and time when the resource was created (ISO 8601 format). | | `description` | `string \| null` | - | The description of the metafield definition. | | `id` | `string` | - | The resource's unique identifier (UUID). | | `key` | `string` | - | The unique identifier for the metafield definition within its namespace. | | `metafieldsCount` | `integer` | - | The count of the metafields that belong to the metafield definition. | | `name` | `string` | - | The human-readable name of the metafield definition. | | `namespace` | `string` | - | The container for a group of metafields that the metafield definition is associated with. | | `ownerType` | `"/api/metafield_owner_types/products" \| "/api/metafield_owner_types/collections" \| "/api/metafield_owner_types/variants" \| "/api/metafield_owner_types/sale_offers" \| "/api/metafield_owner_types/purchase_offers"` | Yes | The resource type that the metafield definition is attached to. | | `type` | `"/api/metafield_definition_types/single_line_text_field" \| "/api/metafield_definition_types/multi_line_text_field" \| "/api/metafield_definition_types/number_integer" \| "/api/metafield_definition_types/number_decimal" \| "/api/metafield_definition_types/json" \| "/api/metafield_definition_types/list__single_line_text_field" \| "/api/metafield_definition_types/list__number_integer" \| "/api/metafield_definition_types/list__number_decimal" \| "/api/metafield_definition_types/list__product_reference" \| "/api/metafield_definition_types/list__media_reference" \| "/api/metafield_definition_types/product_reference" \| "/api/metafield_definition_types/media_reference" \| "/api/metafield_definition_types/metaobject_reference" \| "/api/metafield_definition_types/list__metaobject_reference"` | Yes | The type of data that each of the metafields that belong to the metafield definition will store. | | `updatedAt` | `string` | - | The date and time when the resource was last modified (ISO 8601 format). | | `validations` | `EmbeddedMetafieldDefinitionValidationResource[]` | - | The validation rules applied to the values of metafields using this definition. | ## Errors **400** - Invalid input | Property | Type | Required | Description | | ------------- | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `@context` | `string \| object` | - | | | `@id` | `string` | Yes | | | `@type` | `string` | Yes | | | `code` | `string` | - | Stable identifier of the error in the error code catalogue (see /api/error-codes). Present on catalogued errors only. | | `description` | `string \| null` | - | | | `detail` | `string \| null` | - | A human-readable explanation specific to this occurrence of the problem. | | `instance` | `string \| null` | - | A URI reference that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced. | | `message` | `string` | - | End-user message localized in the request locale, with this occurrence's values substituted. Present on catalogued errors only. | | `slug` | `string` | - | Stable, readable key of the error in the error code catalogue. Present on catalogued errors only. | | `status` | `integer \| null` | - | | | `title` | `string \| null` | - | A short, human-readable summary of the problem. For a catalogued error it repeats the `slug`. | | `type` | `string` | - | A URI reference that identifies the problem type. For a catalogued error it is the error code resource, `/api/error-codes/{code}`. | **403** - Access denied. The caller is missing one or more permissions required for this operation. | Property | Type | Required | Description | | -------------------- | ------------------ | -------- | ---------------------------------------------------------------------------------------------------------------------- | | `@context` | `string \| object` | - | | | `@id` | `string` | Yes | | | `@type` | `string` | Yes | | | `detail` | `string` | - | | | `missingPermissions` | `string[]` | - | Permissions that the caller is missing for this operation. Present only when the 403 is caused by a denied permission. | | `status` | `integer` | - | | | `title` | `string` | - | | | `type` | `string` | - | | **422** - An error occurred | Property | Type | Required | Description | | ------------- | ------------------ | -------- | ----------- | | `@context` | `string \| object` | - | | | `@id` | `string` | Yes | | | `@type` | `string` | Yes | | | `description` | `string` | - | | | `detail` | `string` | - | | | `instance` | `string \| null` | - | | | `status` | `integer` | - | | | `title` | `string \| null` | - | | | `type` | `string` | - | | | `violations` | `object[]` | - | | ## Examples ### Example request ```bash curl -X POST 'https://.product-management.flowkiwi.net/api/metafield_definitions' \ -H 'Authorization: Bearer {access_token}' \ -H 'Flowkiwi-Api-Version: unstable' \ -H 'Accept: application/ld+json' \ -H 'Content-Type: application/ld+json' \ -d '{ "constraints": [ { "key": "/api/metafield_definition_constraint_types/category", "values": [ "019af8a0-1111-7222-8333-444455556666", "019af8a0-7777-7888-8999-aaaabbbbcccc" ] } ], "description": "Washing and care guidance shown on the product page.", "key": "care_instructions", "name": "Care instructions", "namespace": "custom", "ownerType": "/api/metafield_owner_types/products", "type": "/api/metafield_definition_types/multi_line_text_field" }' ``` ### Example response ```json { "@context": "/api/contexts/MetafieldDefinition", "@id": "/api/metafield_definitions/019afb05-5e6f-7081-8a92-4d5e6f708192", "@type": "MetafieldDefinition", "constraints": [ { "key": "/api/metafield_definition_constraint_types/category", "values": [ "019af8a0-1111-7222-8333-444455556666", "019af8a0-7777-7888-8999-aaaabbbbcccc" ] } ], "createdAt": "2026-01-15T09:30:00+00:00", "description": "Washing and care guidance shown on the product page.", "id": "019afb05-5e6f-7081-8a92-4d5e6f708192", "key": "care_instructions", "metafieldsCount": 0, "name": "Care instructions", "namespace": "custom", "ownerType": "/api/metafield_owner_types/products", "type": "/api/metafield_definition_types/multi_line_text_field", "updatedAt": "2026-01-15T09:30:00+00:00", "validations": [] } ```