Metafields: store custom data on any resource

Need to attach a warranty period to a product, a VIP flag to a customer, or a delivery note to an order? Metafields let you store any structured data on almost every resource in LaunchMyStore and render it in your storefront with a single Liquid (Aqua) expression.

Metafields are made up of two pieces: a definition (the shape and validation of the data) and a value (the data itself, per resource). This guide walks through both.

What is a metafield?

A metafield is a typed, namespaced piece of custom data attached to a single resource. Each metafield has:

• Namespace – a grouping like custom or my_app.
• Key – the machine name, e.g. warranty_years.
• Type – one of 22 supported types (text, number, color, money, references, lists, etc.).
• Value – the actual data stored against a specific resource.

Once defined, values are accessible in Aqua as {{ owner.metafields.namespace.key }}.

The 9 owner types

Metafields can be attached to nine kinds of resources:

Owner type	What it covers	Liquid access
shop	Store-wide settings	shop.metafields
product	Individual products	product.metafields
variant	Product variants (SKUs)	variant.metafields
collection	Collections / categories	collection.metafields
customer	Customer profiles	customer.metafields
order	Orders	order.metafields
page	Static pages	page.metafields
blog	Blogs	blog.metafields
article	Blog articles	article.metafields

Creating a definition

Definitions live in your admin under Settings → Custom data. Pick the resource (e.g. Product), click Add definition, then provide:

1. Name – human label shown in the editor, e.g. “Warranty (years)”.
2. Namespace and key – e.g. custom.warranty_years.
3. Type – pick from the type catalog (see the type reference).
4. Validations – optional rules (min, max, regex, choices, list bounds).
5. Pinned – pinned definitions show up directly on the resource detail page so staff can edit them quickly.

You can also create definitions via the REST API:

POST /metafield-definitions
{
  "namespace": "custom",
  "key": "warranty_years",
  "name": "Warranty (years)",
  "type": "number_integer",
  "ownerType": "product",
  "validations": { "min": 0, "max": 25 },
  "pinned": true
}

Adding values to a resource

Open any product (or other resource) in admin. Pinned definitions appear in a Metafields panel on the right. Fill in the value and save. Behind the scenes this calls POST /metafields/bulk.

Values are unique per (ownerType, namespace, key, ownerId) — resaving updates the existing value instead of creating a duplicate.

Pinned vs. unpinned definitions

Pinned definitions appear inline on every resource detail page, ready to edit. Unpinned definitions still exist and can be set via the API or bulk operations, but they don’t clutter the detail page. Pin the fields your staff edit daily; leave the rest unpinned.

What metafields are not

• They are not a substitute for product options or variants — use variants for SKU-level pricing and stock.
• They are not a replacement for theme settings — theme settings live in config/settings_data.json and control global theme appearance.
• They are not sandboxed per app — pick a unique namespace if you’re building a public app.

FAQ

What’s the difference between a metafield definition and a metafield value?

The definition describes the field once (its type, validation, label). The value is the data stored against a specific resource. Deleting a definition does not delete the existing values — they remain in the database and can be re-attached if you recreate the definition.

Can I rename a metafield’s key after creating it?

No. The combination of (ownerType, namespace, key) is the unique identity of a definition. If you need a new key, create a new definition and migrate the values via the bulk API, then delete the old definition.

Are metafields available in every theme?

Yes. Any Aqua theme can read metafields through the standard {{ owner.metafields.namespace.key }} pattern. No theme code change is required to enable them — just define and set the value.

How many metafields can one resource have?

There’s no hard cap, but bear in mind every metafield ends up in the storefront global object payload. Keep the count reasonable per resource (a few dozen pinned ones is fine, hundreds will slow down page renders).

Can I import metafield values in bulk?

Yes. Use POST /metafields/bulk with an array of value objects. This is the same endpoint the admin editor uses to save a resource’s metafield panel.

Do metafields work for sub-stores?

Yes. Metafield definitions and values are scoped per store, so a sub-store has its own independent set. Parent and child stores do not share metafields.