Add custom data
Outcome: the Copenhagen Lamp carries a typed specs.wattage value assigned through the product aggregate.
Prerequisites
Choose a namespace and key owned by the integration, the narrowest owner type, a value kind, and whether the field is permitted in Storefront. Use metadata instead when only the integration interprets a string value.
1. Create the definition
Use the exact MetafieldCreateInput fields to create an integer product definition for namespace specs, key wattage. Select public visibility only if the input and project policy allow it.
2. Assign through the product
Read ProductUpdateInput.metafields and call productUpdate with the product ID and the typed assigned value. Metafield definition mutations manage definitions; values are part of the owner create/update input.
An unknown definition, wrong owner, or wrong value shape must be treated as a validation failure. Do not serialize 40 into an arbitrary text field to bypass the kind.
3. Verify
Query the Admin product and inspect the concrete metafield type with __typename. If the definition is Storefront-visible, query the Storefront product and confirm the same typed value. If it is not returned, inspect definition visibility rather than duplicating it in metadata.