Manage metafield definitions

Metafield definitions are schemas that specify the structure, type, and rules for metafields. Without definitions, metafields are untyped strings that can't be edited in the Shopify admin or validated.

This guide shows you how to create, read, update, and delete metafield definitions using TOML configuration or the GraphQL Admin API.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the appropriate access scopes for the owner type that you want to associate with the metafield definition. For example, write_products for product metafields, or write_customers for customer metafields.

Anchor to Creating definitionsCreating definitions

There are two ways to create metafield definitions:

• TOML: TOML configurations in shopify.app.toml create app-owned definitions. Your app maintains control over the schema while optionally allowing metafield (value) edits in the Shopify admin.
• GraphQL: The GraphQL Admin API provides programmatic control for creating merchant-owned definitions (editable in the Shopify admin by merchants and all installed apps) and dynamically generating definitions based on user configuration.

Anchor to TOML (app-owned) exampleTOML (app-owned) example

This example creates an app-owned definition that tracks when products were last synchronized. The definition grants merchants write access to metafield values through access.admin = "merchant_read_write", while the definition schema remains app-controlled.

Once you've updated the file, deploy the changes with your app:

Benefits of TOML:

• Definitions are version-controlled as part of your app.
• Automatic creation and updates on deploy.
• Works with shopify app dev to safely test out changes.
• Consistent across all shops - when you update your app's data structure, it deploys to every installation automatically.
• The app maintains ownership.

Anchor to GraphQL Admin API exampleGraphQL Admin API example

These examples show how to create metafield definitions using GraphQL. The first creates a merchant-owned definition that all apps can access. The second creates an app-owned definition that only your app controls.

# POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
# Headers: X-Shopify-Access-Token: {merchant_token}

mutation CreateMerchantOwnedDefinition {
  metafieldDefinitionCreate(
    definition: {
      namespace: "product_details"
      key: "warranty_info"
      name: "Warranty Information"
      description: "Product warranty details and coverage"
      type: "multi_line_text_field"
      ownerType: PRODUCT
      access: {
        storefront: PUBLIC_READ
      }
    }
  ) {
    createdDefinition {
      id
      namespace
      key
    }
    userErrors {
      field
      message
    }
  }
}

# POST https://{shop}.myshopify.com/api/{api_version}/graphql.json
# Headers: X-Shopify-Access-Token: {app_token}

mutation CreateAppOwnedDefinition {
  metafieldDefinitionCreate(
    definition: {
      namespace: "$app" # app-reserved namespace
      key: "warranty_info"
      name: "Warranty Information"
      description: "Product warranty details and coverage"
      type: "multi_line_text_field"
      ownerType: PRODUCT
      access: {
        admin: MERCHANT_READ_WRITE
        storefront: PUBLIC_READ
      }
    }
  ) {
    createdDefinition {
      id
      namespace
      key
    }
    userErrors {
      field
      message
    }
  }
}

Key differences:

• Merchant-owned: Use any non-reserved namespace (like product_details). This provides full control in the Shopify admin—no access.admin needed. Only access.storefront is used to control customer visibility.
• App-owned: Use the reserved $app namespace. The app controls the definition. Use access.admin to grant merchant write permissions.

Anchor to When to use GraphQL vs TOMLWhen to use GraphQL vs TOML

Use TOML when:

• Your app needs fixed, known fields (for example, tracking numbers, warranty dates).
• The structure is consistent across all installations.
• Fields are core to your app's functionality.
• You want a version-controlled, declarative configuration.

Use GraphQL when:

• Merchants define their own custom fields through your app's UI.
• Field structure varies per merchant or changes frequently.
• Building form builders, CMS-like tools, or field managers.
• You're creating merchant-owned fields that other apps can access.

Anchor to Dynamic definition creation exampleDynamic definition creation example

This example shows how to programmatically create definitions based on user input, such as in a field manager app where custom fields are configured through your app's UI.

Your app would collect field configuration (via a form or UI), validate the input, construct the variables object, and then execute the mutation. This enables the creation of custom fields through your app's interface without editing code or configuration files.

Anchor to Reading definitionsReading definitions

Use GraphQL to find existing definitions and check their capabilities.

Query all definitions by resource type:

Search definitions by name or namespace:

Find a specific definition by namespace and key:

Anchor to Updating definitionsUpdating definitions

Only specific fields can be updated after creation:

The following example shows how to update a definition's name, description, and access permissions using the metafieldDefinitionUpdate mutation:

To change a namespace/key:

1. Create a new definition with the desired namespace/key.
2. Copy the existing metafield values to the new namespace/key.
3. Update your app code, extensions, and integrations to reference the new namespace/key.
4. Test thoroughly with both definitions active to ensure everything works.
5. Delete the old definition once migration is complete.

This approach enables safe, zero-downtime migration by allowing you to test with both the old and new metafields active before removing the old one.

Anchor to Deleting definitionsDeleting definitions

For TOML definitions:

1. Remove the definition from your shopify.app.toml file.
2. Deploy the change:

For GraphQL definitions, use the metafieldDefinitionDelete mutation:

Set deleteAllAssociatedMetafields to true to delete all metafield values along with the definition, or false to only delete the definition while preserving existing values.

Anchor to Access controlAccess control

Control who can read and write metafield values using settings on your definition. For comprehensive details, see Permissions.

For app-owned metafields (using the app namespace):

• Merchants can always read all metafields and definitions in their store.
• Only the app can make changes to the definition.
• Use access.admin = "merchant_read_write" to allow value edits in the Shopify admin.

For merchant-owned metafields:

• Merchants always have full control of both the definition and the values.
• The access.storefront setting controls customer visibility.

Anchor to Standard definitionsStandard definitions

Shopify provides pre-defined standard metafield definitions for common use cases like product descriptions, ISBN numbers, and care instructions. These definitions use reserved namespace/key combinations (such as descriptors.subtitle or facts.isbn) that ensure interoperability across themes, apps, and the Shopify ecosystem.

Standard definitions are Shopify-owned with predefined access controls that vary by definition. Values are readable and writable across apps and in the Shopify admin.

Query available standard definitions using the standardMetafieldDefinitionTemplates query:

Enable standard definitions using TOML configuration or the standardMetafieldDefinitionEnable mutation. This example enables the subtitle and ISBN standard definitions for products:

[product.metafields]
standard_metafields = ["descriptors.subtitle", "facts.isbn"]

[product_variant.metafields]
standard_metafields = ["descriptors.subtitle"]

# Enable subtitle standard metafield on product
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/1",
    ownerType: PRODUCT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

# Enable ISBN standard metafield on product
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/3",
    ownerType: PRODUCT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

# Enable subtitle standard metafield on product variant
mutation {
  standardMetafieldDefinitionEnable(
    id: "gid://shopify/StandardMetafieldDefinitionTemplate/1",
    ownerType: PRODUCTVARIANT
  ) {
    createdDefinition {
      name
      key
      namespace
      description
    }
  }
}

For more about standard definitions, see the standard definitions list.

Anchor to Error handlingError handling

Understanding common errors helps you implement proper error handling and provide better user experiences. Most errors occur during definition creation or updates when validations, permissions, or naming conflicts arise.

Anchor to Best practicesBest practices

Following these practices helps ensure maintainable, scalable metafield implementations that work well across development, staging, and production environments. Good naming and planning prevent migration headaches and help make your metafields easier for teams to understand and use.

• Use descriptive namespaces: shipping_settings rather than custom.
• Organize with sub-namespaces: For app-owned metafields, use sub-namespaces to group related fields. In TOML, [product.metafields.analytics.lifetime_value] creates namespace app--{id}--analytics. In GraphQL, use namespace: "$app:analytics".
• Add validations gradually: Start loose, tighten as needed.
• Test in development first: Verify before production.
• Document for your team: Maintain a schema reference.
• Cache definition IDs: Avoid repeated queries.
• Batch related operations: Create multiple definitions together.

Anchor to TOML referenceTOML reference

Metafields are declared in shopify.app.toml using the format [<owner_type>.metafields.app.<key>]. For example, [product.metafields.app.page_count] declares a product metafield with namespace $app and key page_count.

Metafields can be defined on many different resource types. For a full list, see MetafieldOwnerType.

Anchor to TOML limitationsTOML limitations

When using TOML-based declarative definitions, be aware of these constraints:

Anchor to App-reserved namespaceApp-reserved namespace

You can only declare metafield definitions in the app-reserved namespace ($app) to ensure that only the owning app can make changes to definitions. This constraint allows Shopify to guarantee a consistent state between all shops your app is installed on.

Anchor to App-scoped limitsApp-scoped limits

To ensure Shopify can quickly and reliably distribute definitions across shops, you can't make more than 25 metafield changes (creation, update, or deletion) in a single deploy. If you need to make more than 25 changes, do so over multiple deploys.

Anchor to Read-only through Admin APIRead-only through Admin API

Declarative definitions are read-only through the Admin API, and can only be updated or deleted through the TOML configuration file. You can query declarative definitions through the Admin API, but mutations will return an error.

Anchor to Capability supportCapability support

Anchor to Next stepsNext steps

• Learn how to work with metafield values.
• Learn about validation options.
• Learn how to enable filtering and other advanced features.