Call metafieldDefinitionCreate mutation with ownerType (e.g., PRODUCT, VARIANT, CUSTOMER), namespace, key, name, type (e.g., single_line_text_field, number_decimal, json), and validations array
Set pin: true (via metafieldDefinitionPin) to surface the metafield in the Shopify admin product or customer detail view for manual editing by merchants
Add validation rules via the validations array on the definition: e.g., for number types add min and max constraints; for single_line_text add a max character count
Query defined metafields on a resource using metafieldDefinitions query filtered by ownerType to inventory what definitions exist before creating new ones to avoid duplicates
To migrate existing metafields written without a definition to a defined namespace, create the definition first — existing metafields matching the namespace/key will automatically be associated with the definition
Known gotchas
Metafield definitions are immutable for the type field after creation; to change a metafield type you must delete the definition (which deletes all associated metafield values) and recreate it — plan the type carefully before deploying to production
Namespace and key combinations must be unique per ownerType; attempting to create a duplicate namespace+key for the same owner type returns a userErrors response even if the definition was deleted, until the deletion propagates fully
The json metafield type accepts arbitrary JSON but does not enforce a schema; if structured validation is needed, use a more specific type (list.single_line_text_field) or validate the JSON structure in your application before writing
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp