Metafields & metaobjects

When the built-in fields aren’t enough — care instructions, ingredients, size charts, designer bios, ingredient glossaries — metafields and metaobjects hold your custom data. Define a field once, fill it per resource, and render it on your storefront with no code or a one-line Liquid tag.

Everything lives under Settings → Custom data, which has two sections: Metafield Definitions (typed fields on existing resources) and Metaobjects (your own content types and their entries).

Metafields: custom fields on existing things

A metafield definition adds one typed, validated field to a resource. Once defined, the field appears in that resource’s editor — for example, a custom.care_instructions field shows up on every product page ready to fill.

Where you can add fields

On the Custom data page, the Metafield Definitions section lists every resource you can extend. Click a resource to open its definitions list, then Add definition:

Resource	Typical use
Products	Care instructions, ingredients, size notes
Product variants	Per-variant material, fit, supplier codes
Collection	Merchandising copy and content for collection pages
Locations	Opening hours, operational notes
Blogs	Metadata for whole blog containers
Blog Posts	Structured extra data on articles
Customers	Internal preferences, profile data
Store	Store-wide settings and admin-only data
Pages	Structured content fields on store pages
Orders	Fulfilment or customer-service workflow data

Value types

The type you pick controls how values are entered, validated, and rendered. Types are grouped into eight categories in the picker:

Category	Types
Most Used	Single line text, Integer, Boolean, Date, File
Text	Single line text, Multi line text, Rich text
Number	Integer, Decimal
Date and Time	Date, Date time
Measurement	Weight, Volume, Dimension
Reference	File, Metaobject reference, Location, Product reference, Variant reference, Collection reference, Page reference, Blog post reference, Customer reference
Other	Boolean, URL, Money, Color, Rating, Link
Advanced	JSON

That is 26 types in total. A handful of types — Multi line text, Money, JSON, Rich text, and Boolean — can only ever hold a single value; everything else can be turned into a list (for example “list of products” or “list of text”).

Create a definition

1. Go to Settings → Custom data and, under Metafield Definitions, open the resource you want (for example Products).

2. Add definition and enter a Name (for example Care instructions). The Namespace and Key auto-fills from the name as custom.care_instructions. You can edit it, but it must follow namespace.key — letters, numbers, _, -, and exactly one period. Add an optional Description to help staff fill it correctly.

3. Choose a Value Type from the picker. If you chose Metaobject reference, also pick which metaobject definition it points at.

4. Under Number of Values, choose One value or List of values (only shown for types that support lists).

5. Set any Validations for the type (see below), then flip the Access Options you need.

6. For product fields only, optionally assign the definition to product categories so it surfaces as a recommended field when editing products in those categories. Then Save definition.

7. Open any product (or other resource) and fill the new field — it now appears in that resource’s editor.

Caution

After a definition is created, its Namespace and Key, Value Type, Number of Values (single vs list), and referenced metaobject definition are locked. You can still rename it, edit the description, change validations, and toggle access options. To change a locked attribute, delete the definition and create a new one.

Per-type validations

Validations are optional rules the value must satisfy. The fields you see in the Validations card depend on the type:

Type	Validations available
Single line text	Min/max character count and a regex pattern, or a fixed list of preset choices
Multi line text	Min/max character count, regex pattern
Integer	Min/max value
Decimal	Min/max value, max decimal places
File	Accept all file types, or restrict to images and/or videos
Date / Date time	Earliest and latest allowed date (and time)
Weight / Volume / Dimension	Min/max measurement with a unit (e.g. kg, ml, cm)
Rating	Min and max rating bounds (defines the scale)
URL / Link	Allowed URL prefixes and allowed domains
JSON	A JSON schema the value is checked against

Boolean, Color, Money, and the reference types have no extra validations — their type is the constraint.

Access options

Each toggle in Access Options decides where the field is usable. All default to off:

• Required field — the resource can’t be saved without a value.
• Pin definition — pinned definitions appear first in lists and can be reordered, so your most-used fields stay at the top.
• Storefront API access — exposes the field for read access via the public Storefront API (needed for headless and some theme reads).
• Admin Filter — lets you filter products, variants, and other resources by this field inside the admin.
• Automated Collections (products and variants only) — makes the field available as a condition when building automated collections.
• Storefront Filter — lets buyers filter by this field in storefront search and collection filters.
• Customer account — exposes the field in customer-account contexts.

Note

Category assignments are unique to product metafields. Assigning a definition to one or more taxonomy categories means it shows up as a recommended field when you edit products in those categories — so a “Thread count” field is suggested on your bedding products without hunting for it each time.

Showing metafields on your storefront

There are two ways to surface a metafield value, with no rebuild either way.

No code — dynamic sources

In the visual editor, connect a compatible section or block setting to a metafield instead of typing a fixed value. The right value renders per page automatically — one section, configured once. See Dynamic sources for the full list of bindable setting types.

In theme code

Reference the field directly in Liquid from theme code:

{{ product.metafields.custom.care_instructions }}

The same pattern works for other owners — collection.metafields.*, customer.metafields.*, and so on.

Tip

Dynamic sources fail soft: if the metafield is empty or the resource is missing, the setting falls back to nothing rather than breaking the page.

Metaobjects: your own content types

Metaobjects are standalone, reusable content types with their own fields and entries — not attached to a single product. Classic uses: brand/designer profiles, ingredient glossaries, FAQs, size guides, and store locations.

A metaobject has two parts: the definition (the shape — its type key and fields, created under Settings → Custom data) and its entries (the actual records, managed under Content → Metaobjects).

Define a content type

1. On Settings → Custom data, find the Metaobjects section and click Add Definition.

2. Enter a Name (for example Designer). The Type key auto-fills (designer) and, like a metafield key, cannot be changed after creation. Add an optional description.

3. Add Fields — each is typed exactly like a metafield value type. Drag to reorder. Mark one single-line text field as the Display name so entries are easy to identify.

4. Configure Metaobject options (see capabilities below).

5. Save, then add entries.

Capabilities

The Metaobject options section turns on optional behaviours:

• Active-draft status — lets each entry be published or kept as a draft.
• Translations — lets entries be translated into other languages.
• Publish entries as web pages — each entry gets its own URL. When enabled, pick which field supplies the Page title and which supplies the Meta description for SEO. You can also set a URL handle folder, and turn on Online Store to make the data usable in your theme.
• Storefronts API access — exposes the type via the Storefront API.
• Customer Account API access — exposes the type via the Customer Account API.

Note

Published metaobject entries are currently served at /metaobjects/<type>/<handle> (for example /metaobjects/designer/jane-doe). The custom URL handle folder is captured for the future but isn’t live yet — entry pages use the type-based path for now.

Manage entries

Add and edit records under Content → Metaobjects. (Right after you save a new definition, Sellerlane drops you straight into adding its first entry.) Each entry fills the fields you defined; if Active-draft status is on, you control whether it’s published.

Use metaobjects

Reference an entry from a product (or any resource) via a Metaobject reference metafield, or render entries directly in theme code:

{% for designer in metaobjects.designer.values %}
  <h3>{{ designer.name }}</h3>
  <p>{{ designer.bio }}</p>
{% endfor %}

Inspect the live shape from a template with {{ metaobjects | json }}.

Troubleshooting

• Field doesn’t show on the storefront. Confirm the value is actually filled on the resource, and that a dynamic-source binding or Liquid reference exists. For headless or Storefront-API reads, turn on Storefront API access.
• Buyers can’t filter by it. Storefront filtering needs Storefront Filter enabled on the definition; admin-side filtering needs Admin Filter.
• Value rejected on save. It failed a validation — check character counts, min/max bounds, allowed file types, URL domains, or the JSON schema on the definition.
• Can’t change a field’s type or key. Those are immutable after creation. Delete and recreate the definition (existing values won’t carry over).
• Metaobject entry has no public page. The type needs Publish entries as web pages enabled, and the specific entry must be published (when Active-draft status is on).

Next steps

• Dynamic sources — bind settings to metafields, no code.
• Metaobjects & web pages — entry pages and SEO in depth.
• Search & discovery — turn filterable metafields into storefront filters.
• Customers & segments — segment on customer metafields.
• Edit theme code — render values in Liquid.