Define custom data and metaobjects

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

You create the definition in Settings, then fill in values or add entries. Code themes read this data through the storefront API.

Add a field to a part of your store

The Custom data page lists nine parts that can have a metafield: 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 to add a field to, for example Orders.
3. Click Add definition.
4. Enter a Name.
5. Choose the Type.
6. Click Save.

For the detailed steps, the options and how to fill in values for a product, see Add custom data fields. The other parts work the same way. You fill in values in the Metafields section on each record’s page, for example an order’s detail page. The values for Shop are filled in at Settings › General settings.

Each part can have up to 100 definitions.

Create a content type with a metaobject

The example below creates a Feedback 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 Feedback. The type handle just below the box fills in from the name, for example feedback. Themes and the API find the metaobject by this handle.
4. In the Fields card, click Add field.
5. Enter the field name in the Name box, for example Customer name.
6. In the Select type box, choose a type, for example Single line text.
7. Repeat steps 4 to 6 for each other field, for example Message of type Multi-line text and Stars of type Integer.
8. In Metaobject options, turn on Storefront API access if your theme needs to read the entries.
9. In Field options, check that Display name is the field used as each entry’s name, for example Customer name.
10. Click Save.

Display name can only be a Single line text field, so have at least one field of this type. A definition can have up to 40 fields, and a store can have up to 100 metaobject definitions.

To filter entries by a field when you read them through the API, for example by number of stars, add that field to Fields used as filters. You can choose up to 5 fields of type single line text, true or false, integer or date.

Add an entry to a metaobject

1. In the sidebar, click Content › Metaobjects.
2. Click the metaobject’s name, for example Feedback.
3. Click Add entry.
4. Fill in the fields in the Fields card.
5. Under Status, choose Draft if you do not want the entry to show on the storefront yet. A new entry is Active by default.
6. Click Save.

The Handle is created from the display name. Themes and the API find an entry by this handle, so you can edit it to make it easier to remember, using only lowercase letters, digits and hyphens.

On a phone, tap the menu icon in the top left corner to open the sidebar.

Attach an entry to a product

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

1. Go to Settings › Custom data.
2. In the Metafield definitions card, choose Products.
3. Click Add definition.
4. Enter a Name, for example Featured feedback.
5. Under Type, choose Metaobject. The list of your metaobject definitions appears.
6. Choose the Feedback definition from that list.
7. Under Options, turn on Storefront access.
8. Click Save.
9. Open a product you have already saved and find the Metafields section.
10. If the field has no input yet, click the button named after the field, for example Featured feedback.
11. Choose a Feedback entry.
12. Click Save on the product page.

Read the data in a code theme

Code themes use the @ecomweb/storefront-kit package. Metafield values with storefront access turned on come with the product, variant, collection, page, blog post and shop.

• metafield(product, “custom.featured_feedback”) returns the attached entry, or undefined if there is none, or if the Feedback definition does not have Storefront API access turned on.
• metaobjectField(entry, “message”) reads one field of that entry by the field’s key.
• getMetaobjects(storeRef, "feedback", { limit: 10 }) reads the list of active entries, up to 50 at a time.
• getMetaobject(storeRef, "feedback", "<handle>") reads one entry.

Each field’s key shows in the small line under the field when you click the arrow icon Show details on the definition page.

Work with the CLI

# See the metaobject definitions
$ ecomweb metaobject-definitions list
# See the entries of a metaobject, filtered by a filter field
$ ecomweb metaobjects list --type feedback --filter stars=5
# See the fields you need to send when creating a definition
$ ecomweb describe metaobject-definitions

Delete an entry

1. In the sidebar, click Content › Metaobjects.
2. Click the metaobject’s name.
3. On the entry’s row, click the three dots Entry actions.
4. Select Delete.
5. Click Delete entry to confirm.

Fields that reference that entry show it as deleted.

Delete a metaobject definition

1. Go to Settings › Custom data.
2. In the Metaobject definitions card, click the definition’s name.
3. Click the three dots More actions at the top of the page.
4. Select Delete metaobject.
5. Click Delete metaobject to confirm.

If a metafield or another metaobject references this definition, EcomWeb tells you the names of those references. Remove them first, then delete again.

Frequently asked questions