GraphQL Admin API version 2025-01,

Shopify App Store
1

I have a public embedded Shopify app that’s actively used by many merchants and is listed under my Partner account. While reviewing the API Health Report, I received the following notice:

“As of GraphQL Admin API version 2025-01, the metafieldDelete mutation will be removed. Use the metafieldsDelete mutation instead.”
Fix by: 5 days left (October 1, 2025)

I’d like to confirm a few things:

  1. Is October 1, 2025 the actual enforcement date for this deprecation?

  2. Will the metafieldDelete mutation stop functioning after this date?

  3. Has anyone already migrated to metafieldsDelete? If so, are there any tips, caveats, or changes in behavior I should be aware of?

2

Hi @Nithin_K

After October 1st the metafieldDelete mutation will be removed from the 2025-01 API version and all versions after 2025-01. If your app uses metafieldDelete and upgrades to 2025-01 or later (which will be all active supported versions) calls to metafieldDelete will fail.

How to migrate:

  • Instead of passing a metafield GID (ID) to metafieldDelete, you must pass an array of MetafieldIdentifierInput objects to metafieldsDelete.
  • Each MetafieldIdentifierInput requires:
    • ownerId (the GID of the resource the metafield belongs to)
    • namespace (string)
    • key (string)

Example migration:

Old (deprecated, will break in 2025-01+):

mutation {
  metafieldDelete(input: { id: "gid://shopify/Metafield/123456789" }) {
    deletedMetafieldId
    userErrors {
      field
      message
    }
  }
}

New (required for 2025-01+):

mutation {
  metafieldsDelete(metafields: [
    {
      ownerId: "gid://shopify/Product/20995642"
      namespace: "inventory"
      key: "today"
    }
  ]) {
    deletedMetafields {
      key
      namespace
      ownerId
    }
    userErrors {
      field
      message
    }
  }
}

See this metafieldsDelete reference doc and the changelog post about this deprecation for more details.