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, a metafield 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	Product ID string	exists check
variant_reference	Variant ID	Variant ID string	exists check
collection_reference	Collection ID	Collection ID string	exists check
customer_reference	Customer ID	Customer ID string	exists check
page_reference	Page ID	Page ID string	exists check
file_reference	File ID	URL string	exists check

Note on reference types: reference metafields store the ID of the linked resource, and that is what your theme receives in Aqua — the raw ID string, not a fully populated resource object. The one exception is file_reference, which renders the file’s URL (and exposes image/video sub-properties). To turn a stored ID into a usable link or to read the linked resource’s fields, look the resource up yourself in your theme. (Automatic resolution for the other reference types is planned for a future update.)

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 — they store the linked resource’s ID, which keeps the link stable even if the resource is renamed. In your theme you read back that ID (look the resource up yourself if you need its fields), except for file_reference, which gives you the file URL directly.
• 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 (the stored ID) still exists, but the resource it points to is gone, so anything you build from that ID won’t resolve. Guard your theme with {% if product.metafields.custom.related_product %} and confirm the target still exists before relying on it.

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 stored value 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.