Skip to content

Shopify Dude Fix

Shopify Metafields Differ Between Stage and Production: Compare Definitions Before Values

Metafield and metaobject schema drift can break a Shopify theme or app after deployment. Compare definitions by owner, namespace, key, type, access, and validations before syncing values.

Quick answer

On this page

Compare metafield and metaobject definitions between staging and production before copying any values. Match metafields by owner type, namespace, and key; match metaobjects by type and field keys. Classify missing, different, matching, and production-only definitions. Then apply only the safe changes. A field that looks identical in the admin can have a different type, validation rule, access policy, or reference target.

Why copying values first causes trouble

A development store acquires a new product metafield for a promotional price, a page metafield for a hero, and a metaobject for reusable content. Production has an older version of one definition, no version of another, and a third field with a conflicting type. The theme code deploys successfully, but a dynamic source is empty, a GraphQL mutation returns a validation error, or a merchant cannot edit the field in the expected admin screen.

The underlying problem is schema drift. Shopify stores custom-data definitions separately for each shop. A theme deploy does not automatically reproduce every merchant-owned metafield definition or metaobject type in another shop. Values are not a substitute for definitions: the definition supplies type validation, admin editing, access, and other capabilities.

Build a useful comparison key

For each metafield, record ownerType + namespace + key, then compare the type, validations, access permissions, capabilities, constraints, name, and description. The first three identify the field’s role; the remaining properties determine whether the two environments behave the same. For metaobjects, compare the metaobject type, each field key and type, required flags, validations, and relevant capabilities. Do not match only on a friendly label such as “Promo Price.”

Definition GIDs are shop-specific identifiers. They are useful for addressing a definition inside one store, not for deciding whether two stores have equivalent schemas. This also matters after an app uninstall and reinstall: Shopify warns that definition IDs may change.

Start with read-only GraphQL inventory

Query each store with its own authorized Admin API token. The following minimal query lists product metafield definitions. Run the same query with PRODUCTVARIANT, COLLECTION, PAGE, CUSTOMER, and other owner types used by the project. Follow pageInfo.endCursor until hasNextPage is false.

query ProductMetafieldDefinitions($cursor: String) {
  metafieldDefinitions(ownerType: PRODUCT, first: 100, after: $cursor) {
    nodes {
      id
      namespace
      key
      name
      type { name }
      validations { name value }
    }
    pageInfo { hasNextPage endCursor }
  }
}

For metaobjects, inspect the type and field definitions rather than querying individual entries:

query MetaobjectSchemas($cursor: String) {
  metaobjectDefinitions(first: 100, after: $cursor) {
    nodes {
      id
      type
      name
      fieldDefinitions {
        key
        name
        type { name }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}

These are deliberately minimal inventory queries. Expand the selection to include access, validations, required flags, capabilities, and constraints supported by the API version you are targeting. A report that compares only names and types is a starting point, not a complete compatibility check.

Sort the differences into actions, not just a giant list

Missing in production: the staging definition exists but the production counterpart does not. Check ownership and create the definition before importing values or deploying a feature that depends on it.

Different: both exist under the same key, but important properties differ. A changed label is usually low risk. A type mismatch, incompatible validation, different reference target, or storefront access change can break a feature and needs a migration plan.

Matching: the meaningful schema properties agree. You can then test sample values and consumers without rewriting definitions unnecessarily.

Production-only: the field is present in production but not staging. Do not assume it is obsolete. It may support a live integration, an old theme, a report, or a third-party app. Mark it for investigation, not deletion.

Respect the ownership boundary

Shopify’s recommended path for fixed app-owned definitions is declarative TOML in shopify.app.toml. The app owns those schemas and deploys them with the app. Merchant-owned fields under namespaces such as custom are created and managed through Shopify Admin or GraphQL, and can be shared with other authorized apps. They cannot be declared as merchant-owned definitions in shopify.app.toml.

Do not use a synchronization tool to overwrite app-owned definitions belonging to another app. If a merchant-owned definition needs a structural change, check Shopify’s supported update rules. Type and namespace/key changes should be treated as migrations rather than blindly replayed as updates. A safe rename of a namespace/key creates a new definition, copies compatible values, updates consumers, tests both fields in parallel, and removes the old definition only after dependencies are gone.

Make stale-entry cleanup a separate process

A definition with no recent edits is not necessarily stale. Shopify’s own metadata may tell you when a definition was created or updated, but it cannot prove that a theme, Function, Flow, app, report, or integration has stopped reading it. Keep an inventory of references and an owner for each proposed removal. Use a review window and a rollback plan. Never let a “sync” button automatically delete production-only definitions.

When deleting a GraphQL-managed definition, Shopify provides a choice about deleting associated values. That is a data-loss decision, not housekeeping. Preserve values unless there is a reviewed reason to remove them, and verify whether the affected definition is app-owned or merchant-owned.

Common misunderstanding

“The metafield exists in both stores, so we are synchronized.” Two fields with the same name can disagree about owner type, key, data type, validation, reference target, or access. Conversely, two definitions with different GIDs may be semantically identical. Compare the schema, not the label or GID.

How to test this

  1. Run a read-only inventory in staging and production for every owner type and metaobject type in use. Confirm pagination reaches the end.
  2. Choose one matching field, one missing field, one validation mismatch, and one production-only field. Verify that the comparison categorizes each correctly.
  3. Create a missing definition in a test store, then write a representative value. Check the Shopify admin editor and GraphQL readback.
  4. Render a real theme dynamic source or Liquid reference, and exercise any Function, Flow, or extension that consumes the field.
  5. Attempt an invalid value in the test environment to confirm validations behave as expected. Do not run destructive definition changes on production to “see what happens.”
  6. Re-run the diff after changes and confirm only intended differences disappeared. Record production-only fields for review rather than deleting them.

Sources and further reading

Technical references checked October 26, 2026.