Add custom data fields

Custom data fields, called metafields, store extra information on a product that the product form doesn't have, for example a care guide or the material. You create the definition once, then fill in the value on each product.

The value doesn't show in your store by itself. The theme has to read the field, so the last part of this article is for people who edit theme code.

Create a definition for products

1. Go to Settings › Custom data.
2. In the Metafield definitions section, choose Products.
3. Click Add definition.
4. Enter the Name, for example Care guide. The code right below the field fills in from the name, for example custom.care_guide.
5. Under Type, choose a type, for example Multi-line text.
6. In the Options section, turn on Storefront access if you want the theme to be able to read the value.
7. Click Save.

You add fields for variants, collections, pages, posts and the other parts in the Metafield definitions list the same way.

Fill in the value for a product

1. Go to Products and open a saved product.
2. Find the Metafields section.
3. If the field has no input yet, click the button with the field’s name, for example Care guide.
4. Enter the value.
5. Click Save.

The Metafields section is only on saved products. To make a field always show an input at the top of the section, click Pin on the definition page.

Read the value in theme code

When a definition has Storefront access turned on, the storefront API returns the value with the product in the metafields field, by namespace and key. A code theme using the @ecomweb/storefront-kit package reads the value with the metafield function:

The function returns undefined when the product has no value yet, or when the definition doesn’t have Storefront access turned on. For the Rich text type, show the value with the RichText component from the same package.

Set values with the CLI

If you use the EcomWeb CLI, you can view definitions and set values without opening the dashboard.

# List the definitions for products
$ ecomweb metafield-definitions list --owner-type product
# Set a value for one product
$ ecomweb metafields set --owner product:<product-id> --key custom.care_guide --value '"Wash in cold water"'

Delete a definition

1. Go to Settings › Custom data and choose Products.
2. Open the definition you want to delete.
3. Click More actions › Delete definition.
4. Click Delete definition to confirm.