Managing custom fields

Use Settings > Custom fields to define extra information for products, variants, collections, customers, orders, pages, and blog posts. For example, define a Material field for products, then choose the material separately on each product.

A definition sets the field's name, key, type, and rules. A value is the information entered for one record. Creating a definition makes it available to records of the selected type; it does not fill in their values automatically.

Before you start

• Sign in as the store owner or with permission to manage Custom fields. You also need access to the records you want to edit.
• Decide which kind of record needs the information. A product field and a variant field are separate definitions.
• Choose whether the information is for staff or should be available to your storefront theme.
• Plan the key, field type, and whether the field accepts several values before saving. These controls are locked when you reopen an existing definition.

The examples below use an unsaved product definition named Material, with the choices Cotton, Linen, and Wool. The screenshots show how to prepare the form; no definition or product value was saved for these captures.

Open custom fields and choose a record type

1. Open Settings > Custom fields.
2. Use the record-type dropdown above the table. It starts with Products and also offers Variants, Collections, Customers, Orders, Pages, and Blog posts.
3. Search by the definition's name or full key if needed. Search applies within the selected record type.
4. Click Add definition to create a field for that type, or open an existing row to review it.

The demo store has no product definitions. Select any screenshot to enlarge it.

For existing definitions, the table shows Name, Key, Type, and Storefront. The displayed key includes the namespace, such as custom.material. Use the copy action beside it when sharing the handle with someone working on your theme or integration. Visible and Hidden indicate theme access, not proof that a field appears on a storefront page.

Create a definition

1. Select the correct record type, then click Add definition.
2. Enter a clear Name, such as Material.
3. Review Key. Nevuto suggests a key from the name, such as material. Use a lowercase letter first, followed by lowercase letters, numbers, or underscores, up to 64 characters. The key must be unique within this record type and namespace.
4. Optionally add Help text to explain what staff should enter.
5. Choose the Type, validation rules, and visibility settings described below.
6. Review the definition and click Edit at the top right to save it. The current screen uses this label for the submit action on both new and existing definitions.
7. Return to the list and reopen the definition to confirm its saved settings.

An unsaved example. Renaming a new field updates the suggested key until you edit the key yourself. Fields created here use the custom namespace, so this example's full handle is custom.material.

Choose a field type and validation rules

Choose a type that matches the information you intend to store:

• Text, Multi-line text, and Rich text store written content. Text is a good fit for short labels or predefined choices; Multi-line text suits longer plain text; Rich text supports formatted content.
• Integer stores whole numbers, while Decimal supports fractional numbers. Money and Rating provide controls for those values.
• True/False represents a yes/no value.
• Date and Date and time store calendar or timestamp information. Color and URL provide controls for colors and links.
• Image or file, Product, Variant, and Collection reference another resource rather than requiring you to paste its identifier as plain text.
• JSON is for structured data. Use it when the integration or theme consuming the field expects that structure.

The real type menu is scrollable; this image shows its first options. The example is still unsaved.

Where offered, Accept several values makes the field a list instead of a single value. True/False and JSON do not offer this option. A list can have a Maximum number of values.

Available rules depend on the selected type. The form can offer minimum and maximum values, text length limits, decimal places, or a Pattern. A Pattern is a regular expression; use one only when you have a specific format to enforce. Changing a new field's type clears its validation rules, so review the form again after switching types.

For a dropdown, keep Type set to Text and add entries under Choices. Enter a choice and press Enter or use the add action, then repeat for each option. Leaving Choices empty allows free text. Enable Accept several values if staff should be able to select several choices rather than one.

Control theme access and admin filters

In Where it appears, choose the settings appropriate for the field:

• Available to your theme is off by default. Enable it only for information your theme should be able to read. Keep internal notes and private operational details hidden.
• Filter records by this field adds the definition to filters on the corresponding admin record list. The current form offers it for a single True/False value or a single Text value with Choices. It is not offered for lists or variants, which have no separate record list.

This prepared example permits one material per product and enables both theme access and an admin filter. The checkboxes have not been saved.

For the Material example, the form shows the theme handle as metafields.custom.material. Give your theme developer the full handle, record type, and expected value type. Fill in a value on a record and check your theme's preview before relying on its storefront appearance.

Add values to individual records

After saving the definition:

1. Open a record of the same type, such as a product for a Products definition.
2. Find Custom fields and click Add custom fields. In a compact sidebar, use the add icon with that label.
3. Select the existing definition in the picker and click Save. This adds it to the record's local editor; finish saving the record's changes as well.
4. Enter a value in the field's control. Use the row's Edit action for fields edited in a drawer. Compact panels have an Edit custom fields action.
5. Use the page's main save action when the field editor is part of that page's save flow. On a record such as an existing customer or order, the Custom fields block shows its own Save and Discard actions after changes.
6. Reopen the record to confirm that the value persisted.

On an existing record, the drawer's Save action can also save custom field values directly. Close returns to the page without saving those edits; they remain in the local editor until you save or discard them. For a new record, finish the page's create/save flow so there is a record to attach the values to.

The record's Custom fields block lists fields added to that record, rather than every definition available in settings. An empty block does not mean no definitions exist. New-record forms save their field values after the record itself has been created.

Clear value empties a field but keeps it on that record. Remove field removes the field and its value from that record after saving. Neither action deletes the shared definition or changes other records.

Edit or delete a definition

Open an existing definition from Settings > Custom fields, or choose Edit in its row menu. You can update its name, help text, validation rules, theme access, and eligible filtering setting. Key, Type, and Accept several values are locked in the existing-definition form. Create a separate definition if you need a different structure, then review and transfer values deliberately.

Changing validation rules does not automatically rewrite existing values. Check affected records before tightening rules, and resolve validation messages when saving new or edited values.

Definitions marked Managed by an app belong to that app. Merchant changes to their definition are restricted, and their Delete action is disabled. Use the app's supported configuration or contact its developer.

To delete a merchant-managed definition:

1. Check whether a theme or integration uses its full handle.
2. Open Delete from the row menu or the definition editor.
3. Read the confirmation. Deleting from the list keeps existing values. In the full editor's confirmation, an additional Delete the values too. This cannot be undone. checkbox is offered when values exist.
4. Confirm only after choosing whether to retain the values.

Without the extra checkbox, stored values survive without a definition and stop being available to the storefront theme. Recreating the same key under the same record type and namespace can reconnect retained values that satisfy the new type and rules. Incompatible values are kept separately; do not assume a new definition converts them all.

Selecting Delete the values too permanently removes the associated values as well as the definition. Recreating the definition does not restore those deleted values.

Troubleshooting