# Metafields: store custom data on any resource

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 typeWhat it coversLiquid access shopStore-wide settingsshop.metafields
productIndividual productsproduct.metafields variantProduct variants
(SKUs)variant.metafields collectionCollections / categoriescollection.metafields
customerCustomer profilescustomer.metafields orderOrdersorder.metafields
pageStatic pagespage.metafields blogBlogsblog.metafields articleBlog
articlesarticle.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
    [https://docs.launchmystore.io/aqua/metafields]).
 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.