List metafield definitions

get /api/metafield_definitions

Retrieves the collection of MetafieldDefinition resources.

Returns a paginated collection of metafield definitions in the current organization. Filter by ownerType to see the custom fields defined for a given resource.

Query parameters

Name	Type	Required	Description
`page`	`integer`	-	The collection page number
`itemsPerPage`	`integer`	-	The number of items per page
`properties[]`	`string[]`	-	Allows you to reduce the response to contain only the properties you need. If your desired property is nested, you can address it using nested arrays. Example: properties[]={propertyName}&properties[]={anotherPropertyName}&properties[{nestedPropertyParent}][]={nestedProperty}
`id[]`	`string[]`	-	Only the items with one of these ids, each a UUID or the item IRI.
`ownerType`	`string`	-	MetafieldDefinition ownerType
`ownerType[]`	`string[]`	-	MetafieldDefinition ownerType
`type`	`string`	-	MetafieldDefinition type
`type[]`	`string[]`	-	MetafieldDefinition type
`name`	`string`	-	MetafieldDefinition name
`name[]`	`string[]`	-	MetafieldDefinition name
`order[name]`	`string`	-	MetafieldDefinition order[name]
`order[createdAt]`	`string`	-	MetafieldDefinition order[createdAt]
`order[updatedAt]`	`string`	-	MetafieldDefinition order[updatedAt]

Response

200 - MetafieldDefinition collection

Format

Property Type Required Description

search object -

Show search fields

Property Type Required Description

@type string -

mapping object[] -

Show mapping fields

Property	Type	Required
`@type`	`string`	-
`property`	`string \| null`	-
`required`	`boolean`	-
`variable`	`string`	-

template string -

variableRepresentation string -

totalItems integer -

view object -

Show view fields

Property	Type	Required
`@id`	`string`	-
`@type`	`string`	-
`first`	`string \| null`	-
`last`	`string \| null`	-
`next`	`string \| null`	-
`previous`	`string \| null`	-

member MetafieldDefinition[] required

Show member fields

Property Type Required Description

@context string | object -

@id string required

@type string required

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.

Errors

403 - Access denied. The caller is missing one or more permissions required for this operation.

Content-Type: application/problem+json

Property	Type	Required	Description
`@context`	`string \| object`	-
`@id`	`string`	required
`@type`	`string`	required
`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`	-