Metafield types reference (22 supported types)

LaunchMyStore supports 22 metafield types — everything from a plain text label to a typed money object to a list of product references. Picking the right type means automatic validation, type-aware Aqua rendering, and predictable behavior across the admin, API and storefront.

How types work

Each metafield has a type string (e.g. number_integer, list.product_reference). When you upsert a value, the backend validator coerces it to the expected JS shape, applies type-specific structural checks, then enforces any validation rules from the definition (min, max, regex, choices, etc.).

At render time, the MetafieldValueDrop in your theme prints the type-correct string when you use {{ ... }}, but you can also access .value and .type explicitly.

Type catalog

Type	Stored as	Aqua output	Common validations
single_line_text_field	String (no newlines)	String	min, max, regex, choices
multi_line_text_field	String	String	min, max, regex
rich_text_field	HTML / JSON	Raw HTML	—
number_integer	Integer	Integer	min, max
number_decimal	Float	Float	min, max, max_precision
boolean	Bool	true / false	—
color	Hex #RRGGBB	Hex string	—
date	ISO YYYY-MM-DD	ISO string	min, max
date_time	ISO date-time	ISO string	min, max
weight	{unit, value}	1.5 KILOGRAMS	min, max
dimension	{unit, value}	10 CENTIMETERS	min, max
volume	{unit, value}	500 MILLILITERS	min, max
money	{amount, currency_code}	Object (pipe through | money)	ISO 4217 currency
rating	{value, scale_min, scale_max}	Object	scale bounds
url	String (URL)	String	allowed_schemes
json	JSON string	Stringified JSON	—
product_reference	Product ID	Resolved product drop	exists check
variant_reference	Variant ID	Resolved variant drop	exists check
collection_reference	Collection ID	Resolved collection drop	exists check
customer_reference	Customer ID	Resolved customer drop	exists check
page_reference	Page ID	Resolved page drop	exists check
file_reference	File ID	URL string	exists check

List variants

Almost every scalar type has a list variant, written as list.<innerType>, e.g. list.product_reference, list.single_line_text_field, list.number_integer. Lists are stored as a JSON-encoded array and accept two extra validations:

• list_min – minimum number of items.
• list_max – maximum number of items.

Inner-type validations (e.g. min, max, regex) are applied to each item.

Units recognised by measurement types

• Weight: KILOGRAMS, GRAMS, POUNDS, OUNCES.
• Dimension: METERS, CENTIMETERS, MILLIMETERS, INCHES, FEET, YARDS.
• Volume: MILLILITERS, CENTILITERS, LITERS, CUBIC_METERS, FLUID_OUNCES, PINTS, QUARTS, GALLONS, plus the IMPERIAL_* variants.

Picking the right type

• Use single_line_text_field for short labels (badges, SKUs); multi_line_text_field for blocks of plain text; rich_text_field when you need formatting.
• Use money instead of number_decimal for prices — you get currency-aware rendering via the | money filter.
• Use references (instead of free text) when linking to another resource — the storefront resolves the linked drop automatically.
• Use json as a last resort. It bypasses validation and shifts complexity into your theme.

FAQ

Can I change a metafield’s type after I create it?

No. Type is part of the validator contract. If you need a different type, create a new definition with a different key and migrate values.

How is rich_text_field output escaped in my theme?

It isn’t — rich_text_field is intentionally output as raw HTML so you can render formatted content. Only allow trusted staff to edit rich text values.

What happens when a reference target is deleted?

The reference value still exists in the database, but resolving it in the storefront returns an empty drop. Guard your theme with {% if product.metafields.custom.related_product %} before using the reference.

Why does my money metafield print as an object?

money values are objects ({amount, currency_code}), so they render as JSON when used bare. Pipe them through the money filter for currency-formatted output: {{ product.metafields.custom.deposit | money }}.

Can a list have mixed types?

No. A list metafield holds items of one inner type. Use json if you genuinely need heterogeneous data.

Is there a length limit on text fields?

The value column accepts arbitrary length, but you should always set min / max validations on text definitions to keep payloads predictable. The admin enforces them at save time.