[Metafields Bug] Apps can create metafields without STRUCTS

Topic summary

A bug prevents apps from creating metafield definitions when unstructured metafields already exist with the same namespace and key combination.

The Problem:

  • Apps can create metafields on orders without first establishing definitions
  • When attempting to retroactively create a definition using metafieldDefinitionCreate, Shopify returns error code UNSTRUCTURED_ALREADY_EXISTS
  • Despite the error, these metafields remain invisible to both merchants and app owners when querying metafieldDefinitions

Impact:

  • App developers cannot properly structure their metafield data after initial creation
  • The issue was previously reported six months ago but remains unresolved

Current Status:
Developers need a solution to create definitions for existing app-scoped metafield values, as the current system blocks definition creation while keeping the unstructured data hidden from standard queries.

Summarized with AI on November 13. AI used: claude-sonnet-4-5-20250929.

I can update an order with a metafield value that does not have a definition. If I then try to create an app definition using my app reserved namespace and key Shopify will return user errors that it already exists.

mutation metafieldDefinitionCreate($definition: MetafieldDefinitionInput!) {
	metafieldDefinitionCreate(definition: $definition) {
		createdDefinition {
			id
		}
		userErrors {
			code
			field
			message
		}
	}
}
"userErrors": [
				{
					"code": "UNSTRUCTURED_ALREADY_EXISTS",
					"field": [
						"definition"
					],
					"message": "Namespace and key is already in use for a set of your metafields."
				}
			]

However, the metafield will remain invisible to the merchant and the app owner when running this query.

query metafieldDefinitionsget {
	metafieldDefinitions(first: 100, ownerType: ORDER) {
		edges {
			node {
				id
				pinnedPosition
				name
				namespace
				ownerType
				key
				 
				  
			}
		}
	}
}

App developers need a way to create metafield definitions for the metafield values their app set.

The bug was previously surfaced six month ago here.
https://community.shopify.com/c/metafields-and-custom-data/trying-to-create-a-metafield-definition-for-a-namespace-key/m-p/1439497