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.
Add a metafield definition
Section titled “Add a metafield definition”A metafield definition can be added to nine parts of a store: Products, Variants, Collections, Customers, Orders, Pages, Blog posts, Locations and Shop.
- Go to Settings › Custom data.
- In the Metafield definitions card, click the part you want, for example Products.
- Click Add definition.
- Enter a Name, for example Care guide. The namespace and key below it fill in from the name, for example
custom.care_guide. - Choose a Type, for example Rich text.
- In Options, turn on Storefront access if storefront code needs to read the value.
- 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.
Create a metaobject definition
Section titled “Create a metaobject definition”The example creates a Feedbacks type to store customer reviews.
- Go to Settings › Custom data.
- In the Metaobject definitions card, click Add definition.
- 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. - In the Fields card, click Add field.
- Enter a Field name, for example Name, and choose its type from Select type, for example Single line text.
- Repeat for each other field, for example Content of type Multi-line text and Rating of type Integer.
- In Metaobject options, turn on Storefront API access if storefront code needs to read the entries.
- In Field options, check that Display name is the field that names each entry.
- 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.
Add an entry
Section titled “Add an entry”- In the sidebar, click Content › Metaobjects.
- Click the metaobject’s name, for example Feedbacks.
- Click Add entry.
- Fill in the fields in the Fields card.
- Under Status, choose Draft if the entry should not reach the storefront yet. A new entry is Active.
- 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.
Attach an entry to a product
Section titled “Attach an entry to a product”To let each product pick one featured feedback, add a metafield of type Metaobject to products.
- Go to Settings › Custom data and choose Products in the Metafield definitions card.
- Click Add definition and enter a Name, for example Featured feedback.
- Under Type, choose Metaobject, then choose the Feedbacks definition from the list.
- In Options, turn on Storefront access, then click Save.
- Open a saved product and find the Metafields section.
- If the field has no input yet, click Add Featured feedback.
- Choose a Feedbacks entry and click Save.
Read metafields in a storefront
Section titled “Read metafields in a storefront”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.
Read metaobjects in a storefront
Section titled “Read metaobjects in a storefront”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")limitis at most 50. The next page starts atnext_cursor.filtertakes 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()returnsnullwhen 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().
Work with the CLI
Section titled “Work with the CLI”The CLI manages the same data without the dashboard. List metafield definitions and set a value on a product:
# List the definitions for productsecomweb metafield-definitions list --owner-type product# Show a product's metafields with their valuesecomweb 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:
# See the metaobject definitionsecomweb metaobject-definitions list# See the entries of a metaobject, filtered by a filter fieldecomweb metaobjects list --type feedbacks --filter rating=5# Add an entryecomweb metaobjects create --type feedbacks --data '{"name":"Lan Anh","content":"Great quality"}'# See the fields to send when creating a definitionecomweb describe metaobject-definitionsmetafield-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.
Delete an entry
Section titled “Delete an entry”- In the sidebar, click Content › Metaobjects and click the metaobject’s name.
- On the entry’s row, click Entry actions, then Delete.
- Click Delete entry to confirm.
Fields that reference the entry show it as deleted.
Delete a definition
Section titled “Delete a definition”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.
Limits
Section titled “Limits”| 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 |
Who can do this?
Section titled “Who can do this?”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.