Skip to content

Define custom data and metaobjects

Custom data comes in two kinds. A metafield adds one typed field to an existing part of a store, such as a product, an order or a customer. A metaobject is a content type you design yourself, for example Feedbacks or FAQ, with entries you add.

You create the definition in the dashboard, then fill in values or add entries. Storefront code reads the data through the Storefront API and @ecomweb/storefront-kit. This guide needs a store, and the CLI sections need the EcomWeb CLI signed in. See the CLI guide at Install and sign in to the EcomWeb CLI.

A metafield definition can be added to nine parts of a store: Products, Variants, Collections, Customers, Orders, Pages, Blog posts, Locations and Shop.

  1. Go to Settings › Custom data.
  2. In the Metafield definitions card, click the part you want, for example Products.
  3. Click Add definition.
  4. Enter a Name, for example Care guide. The namespace and key below it fill in from the name, for example custom.care_guide.
  5. Choose a Type, for example Rich text.
  6. In Options, turn on Storefront access if storefront code needs to read the value.
  7. Click Save.

The namespace, the key and the type cannot be changed after the definition is created. Storefront code reads the value by the namespace.key identifier.

For the dashboard steps to fill in values on a product, see the merchant article Add custom data fields.

The example creates a Feedbacks type to store customer reviews.

  1. Go to Settings › Custom data.
  2. In the Metaobject definitions card, click Add definition.
  3. Enter a Name, for example Feedbacks. The type shown below the box, for example feedbacks, fills in from the name. Storefront code and the API find the metaobject by this type.
  4. In the Fields card, click Add field.
  5. Enter a Field name, for example Name, and choose its type from Select type, for example Single line text.
  6. Repeat for each other field, for example Content of type Multi-line text and Rating of type Integer.
  7. In Metaobject options, turn on Storefront API access if storefront code needs to read the entries.
  8. In Field options, check that Display name is the field that names each entry.
  9. Click Save.

Display name can only be a Single line text field, so the definition needs at least one. Each field gets a key from its name. Click Show details on a field to see it. Storefront code reads a field by this key.

Metaobject options also include Active and draft status, on by default. A draft entry is saved but never reaches the storefront.

To filter entries by a field when you read them, for example by rating, add the field to Fields used as filters. You can choose up to 5 fields, and they must be Single line text, True or false, Integer or Date.

  1. In the sidebar, click Content › Metaobjects.
  2. Click the metaobject’s name, for example Feedbacks.
  3. Click Add entry.
  4. Fill in the fields in the Fields card.
  5. Under Status, choose Draft if the entry should not reach the storefront yet. A new entry is Active.
  6. Click Save.

The Handle is created from the display name. Storefront code and the API find an entry by its handle. You can edit it, using only lowercase letters, digits and hyphens.

To let each product pick one featured feedback, add a metafield of type Metaobject to products.

  1. Go to Settings › Custom data and choose Products in the Metafield definitions card.
  2. Click Add definition and enter a Name, for example Featured feedback.
  3. Under Type, choose Metaobject, then choose the Feedbacks definition from the list.
  4. In Options, turn on Storefront access, then click Save.
  5. Open a saved product and find the Metafields section.
  6. If the field has no input yet, click Add Featured feedback.
  7. Choose a Feedbacks entry and click Save.

When a definition has Storefront access turned on, the Storefront API returns the value in the metafields field of the product, variant, collection, content page, blog post and store. Values come already resolved: a reference to another entry arrives as the entry with its fields, and a file arrives as a URL.

In theme code, read a value with metafield() from @ecomweb/storefront-kit. Pass the resource and the namespace.key identifier:

import { metafield, metaobjectField, RichText } from "@ecomweb/storefront-kit"
import type { ResolvedMetaobjectRef, RichTextRoot } from "@ecomweb/sdk"
const care = metafield<RichTextRoot>(product, "custom.care_guide")
const featured = metafield<ResolvedMetaobjectRef>(product, "custom.featured_feedback")

metafield() returns undefined when:

  • the resource has no value for that field yet
  • the definition does not have Storefront access turned on
  • the value is a reference to something the storefront may not see, for example a draft entry

The type you pass, such as RichTextRoot, is a cast, not a check. Pick it from the definition’s type. A list type returns an array, for example metafield<ResolvedMetaobjectRef[]>(product, "custom.related").

To show a Rich text value, pass it to the RichText component from the same package:

<RichText value={care} />

RichText renders plain h1 to h6, p, ul, ol, li, strong, em and a elements and never sets raw HTML. Links other than http, https and mailto render as text.

To read one field of an attached entry, use metaobjectField() with the field’s key:

<blockquote>{metaobjectField<string>(featured, "content")}</blockquote>

It returns undefined for a missing or hidden value, and for a reference nested deeper than the API resolves.

A metaobject definition with Storefront API access turned on lists its active entries to the storefront. Use getMetaobjects() for a list and getMetaobject() for one entry by handle:

import { getMetaobject, getMetaobjects } from "@ecomweb/storefront-kit"
const { items, next_cursor } = await getMetaobjects(storeRef, "feedbacks", {
filter: { rating: 5 },
limit: 10,
})
const entry = await getMetaobject(storeRef, "feedbacks", "lan-anh")
  • limit is at most 50. The next page starts at next_cursor.
  • filter takes only the fields listed under Fields used as filters, and matches equal values only.
  • A type that does not exist and a type without storefront access both return an empty list. getMetaobject() returns null when the entry or its type is missing or hidden.
  • Neither function caches on the server. If several components in one request need the same data, wrap the call in React’s cache().

The CLI manages the same data without the dashboard. List metafield definitions and set a value on a product:

Terminal window
# List the definitions for products
ecomweb metafield-definitions list --owner-type product
# Show a product's metafields with their values
ecomweb metafields get --owner product:<product-id>
# Set a value for one product (the value is JSON, so text is quoted)
ecomweb metafields set --owner product:<product-id> --key custom.care_guide --value '"Wash in cold water"'

--owner takes product:<id>, variant:<product id>/<variant id>, collection:<id>, customer:<id>, order:<id>, page:<id>, blog_post:<id>, location:<id> or shop. A key without a dot uses the custom namespace. A null value deletes the stored value.

Metaobject definitions and entries have their own commands:

Terminal window
# See the metaobject definitions
ecomweb metaobject-definitions list
# See the entries of a metaobject, filtered by a filter field
ecomweb metaobjects list --type feedbacks --filter rating=5
# Add an entry
ecomweb metaobjects create --type feedbacks --data '{"name":"Lan Anh","content":"Great quality"}'
# See the fields to send when creating a definition
ecomweb describe metaobject-definitions

metafield-definitions, metaobject-definitions and metaobjects also have get, create, update and delete. Add --dry-run to a change to see it without writing. In the CLI, metaobjects list takes up to 100 entries per page, which is more than the storefront.

  1. In the sidebar, click Content › Metaobjects and click the metaobject’s name.
  2. On the entry’s row, click Entry actions, then Delete.
  3. Click Delete entry to confirm.

Fields that reference the entry show it as deleted.

To delete a metafield definition, open it from Settings › Custom data, then choose Delete definition and confirm.

To delete a metaobject definition, open it in the Metaobject definitions card, open the more actions menu at the top of the page and choose Delete metaobject. Deleting it also deletes all its entries, and you cannot undo it. If a metafield or another metaobject references the definition, the dashboard names those references first. Remove them, then delete again.

What Limit
Metafield definitions per part of the store 100
Pinned metafield definitions per part of the store 20
Metaobject definitions per store 100
Fields per metaobject definition 40
Fields used as filters per metaobject definition 5
Entries per page from the Storefront API 50
Size of one metafield value 65,536 bytes

Staff can view definitions and add or edit metaobject entries. Only the store owner and admins can create, edit or delete definitions.

Can I change the type handle or a field’s data type after saving?

Section titled “Can I change the type handle or a field’s data type after saving?”

No. The type handle is created from the name, and a saved field’s data type cannot be changed. You can still change the display name of a definition and of its fields.

Why can’t my theme read a metaobject’s entries?

Section titled “Why can’t my theme read a metaobject’s entries?”

Check two things. The definition must have Storefront API access turned on, and the entry must be Active. A draft entry never reaches the storefront.