Metafields and metadata
Metafields and metadata extend Thor resources for different purposes. A metafield is governed by a reusable typed definition. Metadata is an untyped key-value collection owned directly by one resource.
Definitions and assigned values
A metafield definition establishes namespace, key, kind, owner type, optional default, and Storefront visibility. Supported public owners include product, product variant, category, collection, customer, order, product attribute, and product attribute value.
Definitions have dedicated create, update, reorder, and delete mutations. Assigned values belong to the owning aggregate: set them through the owner’s create or update input, such as ProductCreateInput.metafields or OrderUpdateInput.metafields. There is no separate value-mutation workflow to invent.
Use a namespace controlled by the integration, such as erp.material_code. A definition’s kind determines the accepted input and returned concrete metafield type. Changing or deleting a definition can invalidate consumers, so treat it as a versioned contract.
Metadata
Use metadata for opaque integration bookkeeping such as an import source or external row identifier. Values are strings and do not gain typed validation, default behavior, or a Storefront schema contract.
Choose a metafield when storefronts or Admin tools must understand, validate, filter, or render the value. Choose metadata when only the owning integration interprets it.
Visibility
Storefront exposure is controlled by the definition and the owner’s Storefront type. Do not assume an Admin metafield is public merely because it exists. Query the intended API with the intended owner and inspect the concrete interface type before building a UI dependency.
Example decision
Define specs.wattage as an integer product metafield when storefront filtering and typed display need it. Store erp.source_row as metadata when it only supports synchronization.