Skip to main content
A metafield definition adds a custom field to one kind of record, such as products or orders. You set the field’s name, identifier and data type on this screen, then fill in a value on each record. The admin calls these both metadata definitions and metafield definitions.

​
Where to find it

In the admin, click the Settings gear in the top bar. In the Settings sidebar, under Commerce, select Metadata Definitions.

​
Permissions you need

What you can do here depends on your role’s access to Company Settings and Developer. To see these permissions, open the role on the Roles screen. On the Permissions tab, click the Settings card to open it, then click Company Settings or Developer.
  • To open this screen and browse definitions, the role needs at least View only for both areas.
  • To add, edit, pin or delete definitions, the role also needs the Company Settings permission that starts with Edit company-wide settings and the Developer permission that starts with Manage webhooks and API configuration.
The Developer permissions also let a role view API keys and manage webhooks.

​
Metadata categories

The Metadata Definition Categories card lists the kinds of records you can add fields to. Click a category to open its definitions:
  • Product Metadata
  • Variant Metadata
  • Orders Metadata
  • Customers Metadata
  • Pages Metadata
  • Posts Metadata
  • Media Metadata
  • Enrollments Metadata
  • Collections Metadata
  • Categories Metadata
  • Playlists Metadata

​
Definitions list

The category screen’s header names the category, for example Settings › Metadata › Product Metadata. Click Add Definition to create a definition.
  • The All and Pinned tabs filter the list. Pinned shows only pinned definitions.
  • Use the Search… box to find a definition by its name, namespace, key or description.
The list has five columns: Definition Name, Type, Namespace, Used In and Pinned.
  • Type shows the field’s data type, for example Single Line Text Field.
  • Namespace shows the definition’s full identifier, its namespace and key joined by a dot, for example custom.care_instructions.
  • In the Pinned column, click the pin icon to pin or unpin the definition.
Click a row to open the definition.

​
The definition form

For a new definition, the form’s title names the category, for example New Product Metafield Definition. For a saved definition, the title shows its name. To return to the list, click the back link above the title, for example Product Definitions.
  • Name: the field’s label, up to 100 characters.
  • Namespace and key: two boxes that together make the definition’s unique identifier. The screen shows the identifier under the boxes as namespace.key. You can’t change them after you create the definition.
    • The namespace starts as custom. It can use letters, numbers and underscores, up to 20 characters.
    • The key fills in from Name as you type, for example “Care instructions” becomes care_instructions. It can use lowercase letters, numbers and underscores, up to 30 characters.
    • You can use each namespace and key pair only once for the same kind of record, for example once among your Product Metadata definitions.
  • Description: optional text that explains what the field is for.
  • Select Type: the field’s data type. It starts as Single Line Text Field. When you pick a type, a box shows what the type holds and which validations it supports. You can’t change the type after you create the definition. See Field types.
  • Validations: rules for the field’s values. The options depend on the type. See Validations.
The form also has these settings:
  • Pinned: turn this on to list the definition on the Pinned tab.
  • Locked: turn this on to make the field read-only on records once it has a value. A locked field that has a value shows a lock icon, and you can’t change or clear it in the admin.
  • Position: a whole number, 1 by default.
  • Category Assignments: product categories from your catalog, not the metadata categories above. Click Select Categories to open Assign Categories. Search your product categories, select the ones you want, then click Done.

​
Field types

The Select Type list includes these types, grouped here for reference. Many types also have a list version that holds several values. Its name starts with List Of, for example List Of Single Line Text Field. List versions exist for Single Line Text Field, Number Integer, Number Decimal, Date, Date Time, Color, Url and every reference type.

​
Validations

The Validations section shows only the rules the selected type supports.
  • Minimum and Maximum: for text types, these read Minimum character count and Maximum character count. For number types, they read Minimum value and Maximum value. Text, number, measurement, rating and money types support them.
  • Limit to preset choices: turn this on, then enter options under Preset choices. Click Add choice for each extra option. While it’s on, the form hides the Minimum, Maximum and Regular expression rules. Single Line Text Field, Multi Line Text Field, Number Integer, Number Decimal, Color and Url support it, and so do their list versions. Before you turn it on, clear any Minimum, Maximum or Regular expression values. Before you turn it off, clear every preset choice.
  • Regular expression: a pattern that values must match. Single Line Text Field, Multi Line Text Field and List Of Single Line Text Field support it.
  • Maximum decimal places: for Number Decimal and its list version.
  • Accept specific file types: for file reference types. Select one or more of Images, Videos, Documents or Accept all file types.
  • Required JSON keys and Allowed JSON keys: for Json. Click Add key for each extra key.
Boolean, Page Reference, Product Reference, Variant Reference, Collection Reference and Mixed Reference have no validations.

​
Where fields show up

Each definition appears as a field in the Metafields card on the matching record’s page in the admin, for example on a product, an order or a customer. On a variant’s page, the card is called Variant metafields. Enter a value there to fill in the field for that record. If you can edit the record, the card also has a Manage Definitions button. It opens that category’s definitions on this screen.

​
Add a definition

1

Open the category

On the Metadata Definitions screen, click the category you want to add a field to, for example Product Metadata.
2

Start a new definition

Click Add Definition.
3

Name the field

Enter a Name and, if you want, a Description. If you need a different namespace or key, change it after you finish the name.
4

Choose the type and validations

In Select Type, choose the data type before you set any Validations. If you change the type after you set validations, go back to the list and start the definition again. You can’t change the type or validations after you create the definition.
5

Set the options

Set Pinned, Locked, Position and Category Assignments if you need them.
6

Create the definition

Click Create Definition. You return to the category’s list, where the new definition appears.

​
Edit a definition

1

Open the definition

In the category’s list, click the definition.
2

Make your changes

Change Name, Description, Pinned, Locked, Position or Category Assignments as needed. If the definition has validations, Validation Rules shows them as read-only code under Current rules.
3

Save

Click Save Changes. The button reads Saved when there’s nothing new to save.

​
Delete a definition

1

Open the definition

In the category’s list, click the definition.
2

Choose Delete

Click Delete.
3

Confirm

In the Delete Metafield Definition? dialog, click Delete Definition. You can’t undo this.

​
FAQ

Create a new definition with the type, namespace and key you want.
Check for these common causes:
  • The key is longer than 30 characters, or the namespace is longer than 20. A long name can make a long key, so shorten the key.
  • Another definition for the same kind of record already uses the same namespace and key.
  • You changed Select Type after you set validations. Start again and choose the type first, as in Add a definition.
  • Your role doesn’t have the Developer permission that starts with Manage webhooks and API configuration. See Permissions you need.
On a new definition, the key fills in again from Name each time you edit the name. Finish the name first, then change the key.
Your role doesn’t have the Company Settings permission that starts with Edit company-wide settings. Without it, you can open definitions but can’t change them. See Permissions you need for what your role needs, and ask an admin who manages roles to update your role.
If the Metadata Definition Categories card is empty, or you see Failed to load metadata categories, your role may not have access to Developer. See Permissions you need for what your role needs, and ask an admin who manages roles to update your role.