Admin-API/ext/meta.graphql

# Metafields enable you to attach additional information to a Shopify resource, such as a Product or a Collection.
# For more information about where you can attach metafields refer to HasMetafields.
# Some examples of the data that metafields enable you to store are specifications, size charts, downloadable documents, release dates, images, or part numbers.
# Metafields are identified by an owner resource, namespace, and key. and store a value along with type information for that value.
type Metafield implements LegacyInteroperability&Node{
    # The date and time when the metafield was created.
    createdAt: DateTime!

    # The optional, associated metafield definition that maps to this metafield's namespace and key pair.
    definition: MetafieldDefinition

    # The description of the metafield.
    description: String

    # A globally-unique identifier.
    id: ID!

    # The unique identifier for the metafield in its namespace.
    key: String!

    # The ID of the corresponding resource in the REST Admin API.
    legacyResourceId: UnsignedInt64!

    # A container for a group of metafields.
    # Grouping metafields within a namespace prevents your metafields from conflicting with other metafields that have the same key name.
    namespace: String!

    # The resource that the metafield is attached to.
    owner: HasMetafields!

    # The resource that the metafield is attached to.
    ownerType: MetafieldOwnerType!

    # Returns a reference object if the metafield definition's type is a resource reference.
    reference: MetafieldReference

    # A list of reference objects if the metafield's type is a resource reference list.
    references(
        first: Int
        after: String
        last: Int
        before: String
    ): MetafieldReferenceConnection

    # The type of data that the metafield stores in the value field.
    # See the list of supported types.
    type: String!

    # The date and time when the metafield was updated.
    updatedAt: DateTime!

    # The data to store in the metafield. The data is always stored as a string, regardless of the metafield's type.
    value: String!
}

# Metafield definitions enable you to define additional validation constraints for metafields, and enable the
# merchant to edit metafield values in context.
type MetafieldDefinition implements Node {
    # The description of a metafield definition.
    description: String

    # A globally-unique identifier.
    id: ID!

    # The key name used to identify a metafield definition within a namespace.
    key: String!

    # The list of metafields associated with a metafield definition.
    metafields(
        validationStatus: MetafieldValidationStatus = ANY
        first: Int
        after: String
        last: Int
        before: String
        reverse: Boolean = false
    ): MetafieldConnection!

    # The count of metafields under a metafield definition.
    metafieldsCount(validationStatus: MetafieldValidationStatus): Int!

    # The human-readable name for the metafield definition.
    name: String!

    # The namespace of the metafield definition. You can use a namespace to group related metafields.
    namespace: String!

    # The resource type that the metafield definition is attached to. For example, Product or Collection.
    ownerType: MetafieldOwnerType!

    # The position of the metafield definition in the pinned list.
    pinnedPosition: Int

    # The standard metafield definition template associated with a metafield definition.
    standardTemplate: StandardMetafieldDefinitionTemplate

    # The type of data that the metafield will store.
    type: MetafieldDefinitionType!

    # The validation status for the existing metafields within a metafield definition.
    validationStatus: MetafieldDefinitionValidationStatus!

    # A list of validation options for
    # the metafield. For example, for a metafield with the type date, you can set a minimum date validation, so
    # that the metafield will only store dates after the specific minimum date.
    validations: [MetafieldDefinitionValidation!]!

    # Whether metafields for the metafield definition are visible using the Storefront API.
    visibleToStorefrontApi: Boolean!
}

# Standard metafield definition templates provide preset configurations to create metafield definitions.
# Each template has a specific namespace and key that we've reserved to have specific meanings for common use cases.
#
# Refer to the list of standard metafield definitions.
type StandardMetafieldDefinitionTemplate implements Node {
    # The description of the standard metafield definition.
    description: String

    # A globally-unique identifier.
    id: ID!

    # The key owned by the definition after the definition has been activated.
    key: String!

    # The human-readable name for the standard metafield definition.
    name: String!

    # The namespace owned by the definition after the definition has been activated.
    namespace: String!

    # The list of resource types that the standard metafield definition can be applied to.
    ownerTypes: [MetafieldOwnerType!]!

    # The associated metafield definition type that the metafield stores.
    type: MetafieldDefinitionType!

    # The configured validations for the standard metafield definition.
    validations: [MetafieldDefinitionValidation!]!

    # Whether metafields for the definition are by default visible using the Storefront API.
    visibleToStorefrontApi: Boolean!
}

# A metafield definition type provides basic foundation and validation for a metafield.
type MetafieldDefinitionType {
    # The category associated with the metafield definition type.
    category: String!

    # The name of the type for the metafield definition.
    # See the list of supported types.
    name: String!

    # The supported validations for a metafield definition type.
    supportedValidations: [MetafieldDefinitionSupportedValidation!]!

    # Whether metafields without a definition can be migrated to a definition of this type.
    supportsDefinitionMigrations: Boolean!
}

# The type and name for the optional validation configuration of a metafield.
#
# For example, a supported validation might consist of a max name and a number_integer type.
# This validation can then be used to enforce a maximum character length for a single_line_text_field metafield.
type MetafieldDefinitionSupportedValidation {
    # The name of the metafield definition validation.
    name: String!

    # The type of input for the validation.
    type: String!
}

# A configured metafield definition validation.
#
# For example, for a metafield definition of number_integer type, you can set a validation with the name max
# and a value of 15. This validation will ensure that the value of the metafield is a number less than or equal to 15.
#
# Refer to the list of supported validations.
type MetafieldDefinitionValidation {
    # The validation name.
    name: String!

    # The name for the metafield type of this validation.
    type: String!

    # The validation value.
    value: String
}

# Private metafields represent custom metadata that is attached to a resource.
# Private metafields are accessible only by the application that created them and only from the GraphQL Admin API.
#
# An application can create a maximum of 10 private metafields per shop resource.
type PrivateMetafield implements Node {
    # The date and time when the private metafield was created.
    createdAt: DateTime!

    # The id of the private metafield.
    id: ID!

    # The key name of the private metafield.
    key: String!

    # The namespace of the private metafield.
    namespace: String!

    # The date and time when the private metafield was updated.
    updatedAt: DateTime!

    # The value of a private metafield.
    value: String!

    # Represents the private metafield value type.
    valueType: PrivateMetafieldValueType!
}

# The input fields for a private metafield.
input PrivateMetafieldInput {
    # The resource that owns the metafield. If the field is blank, then the Shop resource owns the metafield.
    owner: ID

    # The namespace of the private metafield.
    namespace: String!

    # The key of the private metafield.
    key: String!

    # The value and valueType of the private metafield, wrapped in a ValueInput object.
    valueInput: PrivateMetafieldValueInput!
}

# The value input contains the value and value type of the private metafield.
input PrivateMetafieldValueInput {
    # The value of a private metafield.
    value: String!

    # Represents the private metafield value type.
    valueType: PrivateMetafieldValueType!
}

# The input fields to use to create or update a metafield through a mutation on the owning resource.
# An alternative way to create or update a metafield is by using the metafieldsSet mutation.
input MetafieldInput {
    # The description of the metafield.
    description: String

    # The unique ID of the metafield. You don't include an ID when you create a metafield because the metafield ID
    # is created automatically. The ID is required when you update a metafield.
    id: ID

    # The namespace for a metafield. The namespace is required when you create a metafield and is optional when you
    # update a metafield.
    namespace: String

    # The key name of the metafield. Required when creating but optional when updating.
    key: String

    # The value of a metafield.
    value: String

    # The metafield's type. The metafield type is required
    # when you create a metafield and is optional when you update a metafield.
    type: String
}

# An auto-generated type for paginating through multiple Metafields.
type MetafieldConnection {
    # A list of edges.
    edges: [MetafieldEdge!]!

    # A list of the nodes contained in MetafieldEdge.
    nodes: [Metafield!]!

    # Information to aid in pagination.
    pageInfo: PageInfo!
}

# An auto-generated type which holds one Metafield and a cursor during pagination.
type MetafieldEdge {
    # A cursor for use in pagination.
    cursor: String!

    # The item at the end of MetafieldEdge.
    node: Metafield!
}

# An auto-generated type for paginating through multiple MetafieldDefinitions.
type MetafieldDefinitionConnection {
    # A list of edges.
    edges: [MetafieldDefinitionEdge!]!

    # A list of the nodes contained in MetafieldDefinitionEdge.
    nodes: [MetafieldDefinition!]!

    # Information to aid in pagination.
    pageInfo: PageInfo!
}

# An auto-generated type which holds one MetafieldDefinition and a cursor during pagination.
type MetafieldDefinitionEdge {
    # A cursor for use in pagination.
    cursor: String!

    # The item at the end of MetafieldDefinitionEdge.
    node: MetafieldDefinition!
}

# An auto-generated type for paginating through multiple PrivateMetafields.
type PrivateMetafieldConnection {
    # A list of edges.
    edges: [PrivateMetafieldEdge!]!

    # A list of the nodes contained in PrivateMetafieldEdge.
    nodes: [PrivateMetafield!]!

    # Information to aid in pagination.
    pageInfo: PageInfo!
}

# An auto-generated type which holds one PrivateMetafield and a cursor during pagination.
type PrivateMetafieldEdge {
    # A cursor for use in pagination.
    cursor: String!

    # The item at the end of PrivateMetafieldEdge.
    node: PrivateMetafield!
}

# An auto-generated type for paginating through multiple MetafieldReferences.
type MetafieldReferenceConnection {
    # A list of edges.
    edges: [MetafieldReferenceEdge!]!

    # A list of the nodes contained in MetafieldReferenceEdge.
    nodes: [MetafieldReference]!

    # Information to aid in pagination.
    pageInfo: PageInfo!
}

# An auto-generated type which holds one MetafieldReference and a cursor during pagination.
type MetafieldReferenceEdge {
    # A cursor for use in pagination.
    cursor: String!

    # The item at the end of MetafieldReferenceEdge.
    node: MetafieldReference
}