Metafield
Defines the structure, validation rules, and permissions for Metafield
objects attached to a specific owner type. Each definition establishes a schema
that metafields must follow, including the data type and validation constraints.
The definition controls access permissions across different APIs, determines whether the metafield can be used for filtering or as a collection condition, and can be constrained to specific resource subtypes.
Anchor to FieldsFields
- access (MetafieldAccess!)
- capabilities (MetafieldCapabilities!)
- constraints (MetafieldDefinitionConstraints)
- description (String)
- id (ID!)
- key (String!)
- metafields (MetafieldConnection!)
- metafieldsCount (Int!)
- name (String!)
- namespace (String!)
- ownerType (MetafieldOwnerType!)
- pinnedPosition (Int)
- standardTemplate (StandardMetafieldDefinitionTemplate)
- type (MetafieldDefinitionType!)
- useAsCollectionCondition (Boolean!)
- validations ([MetafieldDefinitionValidation!]!)
- validationStatus (MetafieldDefinitionValidationStatus!)
- Anchor to accessaccess•Metafield
Access! non-null The access settings associated with the metafield definition.
- Anchor to capabilitiescapabilities•Metafield
Capabilities! non-null The capabilities of the metafield definition.
- Anchor to constraintsconstraints•Metafield
Definition Constraints The constraints that determine what subtypes of resources a metafield definition applies to.
- Anchor to descriptiondescription•String
The description of the metafield definition.
- •ID!non-null
A globally-unique ID.
- •String!non-null
The unique identifier for the metafield definition within its namespace.
- Anchor to metafieldsmetafields•Metafield
Connection! non-null The metafields that belong to the metafield definition.
- Anchor to afterafter•String
The elements that come after the specified cursor.
- Anchor to beforebefore•String
The elements that come before the specified cursor.
- Anchor to firstfirst•Int
The first
nelements from the paginated list.- Anchor to lastlast•Int
The last
nelements from the paginated list.- Anchor to reversereverse•BooleanDefault:false
Reverse the order of the underlying list.
- Anchor to validationStatusvalidation•Metafield
Status Validation Status Default:ANY Returns the metafields filtered by the validation status.
Arguments
- Anchor to metafieldsCountmetafields•Int!
Count non-null The count of the metafields that belong to the metafield definition.
- Anchor to validationStatusvalidation•Metafield
Status Validation Status The current validation status.
Arguments
- Anchor to namename•String!non-null
The human-readable name of the metafield definition.
- Anchor to namespacenamespace•String!non-null
The container for a group of metafields that the metafield definition is associated with.
- Anchor to ownerTypeowner•Metafield
Type Owner Type! non-null The resource type that the metafield definition is attached to.
- Anchor to pinnedPositionpinned•Int
Position The position of the metafield definition in the pinned list.
- Anchor to standardTemplatestandard•Standard
Template Metafield Definition Template The standard metafield definition template associated with the metafield definition.
- Anchor to typetype•Metafield
Definition Type! non-null The type of data that each of the metafields that belong to the metafield definition will store. Refer to the list of supported types.
- Anchor to useAsCollectionConditionuse•Boolean!
As Collection Condition non-null Whether the metafield definition can be used as a collection condition.
- Anchor to validationsvalidations•[Metafield
Definition Validation!]! non-null A list of validation options for the metafields that belong to the metafield definition. For example, for a metafield definition with the type
date, you can set a minimum date validation so that each of the metafields that belong to it can only store dates after the specified minimum.- Anchor to validationStatusvalidation•Metafield
Status Definition Validation Status! non-null The validation status for the metafields that belong to the metafield definition.
Anchor to QueriesQueries
- metafieldDefinition (MetafieldDefinition)
- metafieldDefinitions (MetafieldDefinitionConnection!)
- •query
Retrieves a
by its identifier. You can identify a definition using either its owner type, namespace, and key, or its global ID.Use this query to inspect a definition's configuration, including its data type, validations, access settings, and the count of metafields using it.
- •IDDeprecated
- Anchor to identifieridentifier•Metafield
Definition Identifier Input The identifier of the MetafieldDefinition to return.
Arguments
- •ID
- •query
Returns a list of metafield definitions.
- Anchor to afterafter•String
The elements that come after the specified cursor.
- Anchor to beforebefore•String
The elements that come before the specified cursor.
- Anchor to constraintStatusconstraint•Metafield
Status Definition Constraint Status Filter metafield definitions based on whether they are constrained.
- Anchor to constraintSubtypeconstraint•Metafield
Subtype Definition Constraint Subtype Identifier Filter metafield definitions based on whether they apply to a given resource subtype.
- Anchor to firstfirst•Int
The first
nelements from the paginated list.- •String
Filter metafield definition by key.
- Anchor to lastlast•Int
The last
nelements from the paginated list.- Anchor to namespacenamespace•String
Filter metafield definition by namespace.
- Anchor to ownerTypeowner•Metafield
Type Owner Type! required Filter the metafield definition by the specific owner type.
- Anchor to pinnedStatuspinned•Metafield
Status Definition Pinned Status Default:ANY Filter the metafield definition by the pinned status.
- Anchor to queryquery•String
A filter made up of terms, connectives, modifiers, and comparators.
name type description acceptable_values default_value example_use default string Filter by a case-insensitive search of multiple fields in a document. - query=Bob Norman
-query=title:green hoodiecreated_at time Filter by the date and time when the metafield definition was created. -
-
-id id Filter by idrange.- id:1234
-id:>=1234
-id:<=1234key string Filter by the metafield definition keyfield. - key:some-keynamespace string Filter by the metafield definition namespacefield. - namespace:some-namespaceowner_type string Filter by the metafield definition field. - type string Filter by the metafield definition typefield. - updated_at time Filter by the date and time when the metafield definition was last updated. -
-| You can apply one or more filters to a query. Learn more about Shopify API search syntax.
- Anchor to reversereverse•BooleanDefault:false
Reverse the order of the underlying list.
- Anchor to sortKeysort•Metafield
Key Definition Sort Keys Default:ID Sort the underlying list using a key. If your query is slow or returns an error, then try specifying a sort key that matches the field used in the search.
Arguments
Anchor to MutationsMutations
- metafieldDefinitionCreate (MetafieldDefinitionCreatePayload)
- metafieldDefinitionPin (MetafieldDefinitionPinPayload)
- metafieldDefinitionUnpin (MetafieldDefinitionUnpinPayload)
- metafieldDefinitionUpdate (MetafieldDefinitionUpdatePayload)
- standardMetafieldDefinitionEnable (StandardMetafieldDefinitionEnablePayload)
- •mutation
Creates a
that establishes structure and validation rules for metafields. The definition specifies the data type, validation constraints, and access permissions for metafields with a given namespace and key combination.When you create a new definition, the system validates any existing unstructured metafields matching the same owner type, namespace, and key against it. The system updates each valid metafield's type to match the definition. Invalid metafields remain unchanged but must conform to the definition when updated.
Learn more about creating metafield definitions.
- Anchor to definitiondefinition•Metafield
Definition Input! required Specifies the input fields for a metafield definition.
Arguments
- •mutation
You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed.
- Anchor to definitionIddefinition•ID
Id The id of the metafield definition to pin. Using
identifieris preferred.- Anchor to identifieridentifier•Metafield
Definition Identifier Input The identifier of the metafield definition to pin.
Arguments
- •mutation
You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed.
- Anchor to definitionIddefinition•ID
Id The ID of the metafield definition to unpin. Using
identifieris preferred.- Anchor to identifieridentifier•Metafield
Definition Identifier Input The identifier of the metafield definition to unpin.
Arguments
- •mutation
Updates a
's configuration and settings. You can modify the definition's name, description, validation rules, access settings, capabilities, and constraints.The mutation updates access settings that control visibility across different APIs, such as the GraphQL Admin API, Storefront API, and Customer Account API. It also enables capabilities like admin filtering or unique value validation, and modifies constraints that determine which resource subtypes the definition applies to.
NoteThe type, namespace, key, and owner type identify the definition and so can't be changed.
Note:The type, namespace, key, and owner type identify the definition and so can't be changed.
Note: The type, namespace, key, and owner type identify the definition and so can't be changed.
Learn more about updating metafield definitions.
- Anchor to definitiondefinition•Metafield
Definition Update Input! required The input fields for the metafield definition update.
Arguments
- •mutation
Activates the specified standard metafield definition from its template.
Refer to the list of standard metafield definition templates.
- Anchor to accessaccess•Standard
Metafield Definition Access Input The access settings that apply to each of the metafields that belong to the metafield definition.
- Anchor to capabilitiescapabilities•Metafield
Capability Create Input The capabilities of the metafield definition.
- •ID
The ID of the standard metafield definition template to enable.
- •String
The key of the standard metafield to enable. Used in combination with
namespace.- Anchor to namespacenamespace•String
The namespace of the standard metafield to enable. Used in combination with
key.- Anchor to ownerTypeowner•Metafield
Type Owner Type! required The resource type that the metafield definition is scoped to.
- •BooleanDefault:null
Whether to pin the metafield definition.
- Anchor to useAsCollectionConditionuse•Boolean
As Collection Condition DeprecatedDefault:null - Anchor to visibleToStorefrontApivisible•Boolean
To Storefront Api DeprecatedDefault:null
Arguments