Metafields and metadata
Metafields and metadata
Metafields add typed, named data to supported Thor resources. Metadata stores string key-value pairs on a resource. Choose between them based on who reads the value and what validation it needs.
Choose the right place
| Data | Recommended place |
|---|---|
| Variant price or stock | Native price or inventory records |
| Product color used to select a variant | Attribute and variant selection |
| Translated product description | Translations |
| Lamp wattage displayed and filtered by buyers | Integer metafield |
| External catalog row identifier | Namespaced metadata or your integration mapping |
Do not use custom data to bypass the price, inventory, or customer model. Thor’s native calculations do not derive their inputs from arbitrary metadata.
Definition and value
A metafield definition gives a namespace, key, owner type, kind, and validation settings.
Create the definition first.
Assign a value through the owner’s create or update input, such as ProductUpdateInput.metafields.
Definition mutations manage the field contract; owner mutations manage values.
Choose names such as specs.wattage that will remain meaningful after a UI redesign.
Treat a change of kind or owner as a consumer-facing contract change.
Visibility is a deliberate choice
Set isPrivate explicitly on a new definition.
Only make a field public when its value is intended for the owner’s Storefront surface.
Verify it through that API before building a dependency on it.
Metadata is not a secret store: a string collection does not provide a blanket confidentiality guarantee.
Keep credentials, internal costs, and sensitive operational notes out of public custom data.
Follow Add custom data for a complete definition, value, and read example.