Skip to main content
Custom fields let you store information Spree does not have a field for. A clothing store needs fabric composition, a food store needs allergens, a supplier-managed catalogue needs an internal margin tier. Rather than waiting on a developer to add a database column, you define the field once and your team fills it in. A definition says what the field is called, which records carry it, and what kind of value it holds. Once defined, it appears on every matching record for anyone to fill in. To manage custom fields, navigate to Settings → Custom fields, under the Store group.
Earlier versions of Spree called these metafields. The dashboard says custom fields throughout.

​
Reviewing Your Custom Fields

The Custom field definitions list Each row shows:
  • Label - What the field is called, with its full key beneath, such as custom.warranty.
  • Applies to - Which kind of record carries this field.
  • Type - What kind of value it holds.
  • Storefront - Whether shoppers can see the value.
Use the search box to find a definition by label, namespace or key.

​
How to Create a Custom Field

Click Add custom field. The Add custom field panel
  • Label - What your team reads on the form, such as Warranty.
  • Namespace - Groups fields and avoids naming collisions. Pre-filled with custom, which is right unless you have a reason to separate a set of fields.
  • Key - A short lower-case identifier, such as warranty. The namespace and key together make the full name shown in the list, custom.warranty.
  • Applies to - Which kind of record the field belongs to.
  • Type - What kind of value it holds. See below.
  • Visible on storefront - Whether shoppers see the value.
  • Searchable - Include values in storefront product text search. Short text, long text and number only.
  • Sortable - Allow storefront listings to sort by this field. Short text and number only.
Click Create custom field.
Neither Applies to nor Type can be changed once values exist for a field. Changing the type would leave stored values misinterpreted, so decide both before your team starts filling it in.
Searchable and Sortable need a follow-up step. After enabling either one with Meilisearch, somebody has to run a reindex so existing products pick it up. Ask whoever maintains your store to do this, because the switch alone does not update what is already there.

​
Choosing a type

Pick the narrowest type that fits. A number stored as short text still sorts, but alphabetically rather than numerically, so 10 comes before 9. Switching the type later means starting the field again.

​
What can carry a custom field

Applies to offers 31 kinds of record, covering most of what your store holds.

​
How to Fill In a Custom Field

Open the record the field applies to. Products carry a Custom fields card showing every definition that applies to them. The Custom fields card on a product Enter the values and save the record.
To have a field appear on a product automatically, add it to a product type. Products carrying that type then show the field without anyone assigning it.

​
Filling them in bulk

Product custom fields can be set through the product CSV. Add a column named custom_field.<namespace>.<key>, such as custom_field.custom.material, and fill in a value for each product row. The import template generated for your store already ends with one column per custom field you have defined for products, so you may not need to add the columns by hand.
The column prefix is custom_field.. A file using the older metafield. prefix imports without its custom field values rather than failing, so the import looks successful and the values are silently missing.

​
How to Edit a Custom Field

Open the row menu and choose Edit. You can change the Label, the Key and the storefront switches at any time. Applies to and Type are fixed once values exist.

​
How to Delete a Custom Field

Open the row menu and choose Delete.
Deleting a definition removes the values stored against it on every record. Export anything you need first, because there is no way to recover them afterwards.

​
Further Reading