Metafield definitions

A Metafield definition declares a custom field you can attach to a resource. It sets the field’s namespace and key (which together identify it), the ownerType it applies to (such as product), the type of data it holds, and any validations and constraints that values must satisfy.

Definitions are the schema; the actual values are Metafields stored on individual owner records. Define a field once, then set its value on each product, variant, and so on.

The Metafield definition object

Property	Type	Required	Description
constraints	EmbeddedMetafieldDefinitionConstraintResource[]	-	The constraint rules scoping where this metafield definition applies (e.g. by category or channel).
Show constraints fields Property Type Required Description key "/api/metafield_definition_constraint_types/category" | "/api/metafield_definition_constraint_types/channel" | "/api/metafield_definition_constraint_types/category_channel" required The type of constraint rule values string[] required Array of constraint values. Format depends on the constraint type.
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"	required	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"	required	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.
Show validations fields Property Type Required Description name "/api/metafield_definition_validation_types/min_length" | "/api/metafield_definition_validation_types/max_length" | "/api/metafield_definition_validation_types/min_value" | "/api/metafield_definition_validation_types/max_value" | "/api/metafield_definition_validation_types/max_precision" | "/api/metafield_definition_validation_types/json_schema" | "/api/metafield_definition_validation_types/media_type" | "/api/metafield_definition_validation_types/metaobject_definition" required The type of validation rule value string required The validation parameter value. Format depends on the validation type.

Common workflows

• Add a custom field. Create a definition with a namespace, key, ownerType and type, then set Metafield values on records of that owner type.
• Constrain values. Attach validations (for example a maximum length or a numeric range) so invalid values are rejected when a metafield is written.
• Audit usage. Each definition reports a metafieldsCount - how many records currently carry a value for it. To see how many definitions each owner type has, list the definition counts.

Type compatibility

Which validations and constraints you can attach is not free-form - it depends on the definition’s type, and the API rejects an incompatible combination with 422 Unprocessable Entity. The rules differ for the two:

• Validations depend on the type. A number_decimal accepts numeric validations (min_value, max_value, max_precision); a text type accepts min_length / max_length; a json type accepts json_schema; reference types accept none. The authoritative, always-current list for each type is the allowedValidations field on Metafield definition types - query that resource rather than hard-coding a table.
• Constraints depend on the ownerType, not the type. Constraints (category, channel, category_channel) are scoped to the owner resource. Today only products allows constraints; every other owner type allows none. The authoritative list is the allowedConstraints field on Metafield owner types.

[!TIP] Before creating a definition, read the matching definition type and owner type to see exactly what it accepts. That way your validations and constraints are valid by construction.

Submitting an incompatible rule returns 422 with a message such as Validation "min_value" is not compatible with metafield definition type "single_line_text_field". or Constraint "category" is not compatible with owner type "variants".

Conventions

Authentication and headers

All requests require an OAuth 2.0 bearer token:

Authorization: Bearer <token>

Partial updates

PATCH uses JSON Merge Patch with Content-Type: application/merge-patch+json.