Skip to main content
Custom fields in Spree allow you to attach extra data to nearly any record in your store — without needing to write a single line of code or modify the database. From product materials to internal order notes, custom fields give you the flexibility to store, manage, and display extra information that doesn’t come out of the box. This reduces reliance on developer deployments, makes experimentation easier, and enables faster iteration directly from the admin dashboard.
The screen heading reads Custom field definitions and the menu entry reads Custom fields. Both mean the same thing. Earlier versions of Spree called these metafields.

​
Creating a New Custom Field

To create a custom field definition go to Settings → Custom fields, under the Store group. Spree Commerce custom fields Here you’ll see a list of all existing custom field definitions in your store. Each row shows the Label with its full key beneath it — such as custom.warranty — along with Applies to, Type, and Storefront. To add a new one, click Add custom field in the top right corner. The panel opens with the line “Define a typed field your team can fill in on any matching record.” Creating custom fields in Spree Fill out the form with the required details:
  • Label - the display name for the field, shown in the dashboard and/or storefront, e.g. Material
  • Namespace - used to group custom fields and avoid naming conflicts. Pre-filled with custom
    • Leave it on custom for internal or merchant-defined fields unless you have a reason to group fields separately
    • Avoid using common Spree model names like product, order, or variant as these may conflict with existing integrations
  • Key - the unique identifier for the field, combined with the namespace
    • e.g.: custom.material, custom.internal_note
  • Applies to - choose the record the custom field applies to (see full list below)
  • Type - the format of data the field should accept (see examples below)
  • Visible on storefront - a switch. Turn it on if shoppers should see the value
  • Searchable - “Include values in storefront product text search (short text, long text, and number only).”
  • Sortable - “Allow storefront product listings to sort by this field (short text and number only).”
Then click Create custom field.
The Searchable and Sortable switches need a follow-up step your developers have to run: after enabling either one with Meilisearch, somebody must run rake spree:search:reindex so existing products are updated. Ask whoever maintains your store to do this — the switch alone does not update what is already there.

​
Supported Records

Add a custom field definition in Spree You can define custom fields for nearly any record in Spree. Applies to offers 31:
  • Addresses - e.g., delivery instructions
  • Categories - e.g., display badge (“New”, “Sustainable”)
  • Claims
  • Collections
  • Credit Cards - e.g., vault token
  • Customers - e.g., loyalty tier
  • Delivery Methods - e.g., carrier code
  • Exchanges
  • Fulfillments - e.g., fragile/handling notes
  • Gift Cards - e.g., personal message
  • Line Items - e.g., engraving or personalization notes
  • Media - e.g., alt text, copyright, or display priority
  • Newsletter Subscribers - e.g., subscription source
  • Option Types - e.g., an extended description for color choices
  • Option Values - e.g., color hex code
  • Orders - e.g., internal comment, PO number
  • Payment Methods - e.g., risk profile or processor ID
  • Payment Sources - e.g., metadata from payment gateway
  • Payments - e.g., external transaction reference
  • Product Types
  • Products - e.g., material, sustainability rating, care instructions
  • Promotions - e.g., campaign name
  • Refunds - e.g., refund reason detail
  • Returns - e.g., return reason detail
  • Sellers - e.g., seller profile details
  • Stock Levels - e.g., warehouse bin location
  • Stock Transfers - e.g., batch ID or receiving note
  • Store Credits - e.g., usage restrictions
  • Stores - e.g., store tagline or branding metadata
  • Tax Rates - e.g., compliance category
  • Variants - e.g., spec sheet URL, sizing details

​
Supported Data Types

Spree Commerce custom field types Each custom field must be assigned a type, which determines the format of the stored value. Choosing the right type helps keep data structured, valid, and useful across the storefront and admin.
  • Short Text - for single-line strings, e.g., “Cotton” or “Blue”
  • Long Text - multi-line content, e.g., care instructions
  • Rich Text - text with formatting options, e.g., marketing blocks
  • Number - any numeric value, e.g., 4.5 (rating), 12 (inches)
  • Boolean - true/false flags, e.g., “Is this product fragile?” = true
  • JSON - for structured data or multiple related attributes
Neither Applies to nor Type can be changed once values exist for a field. The edit panel says so: “The type can’t be changed once values exist — switching it would leave stored values misinterpreted.” Decide both before you start filling the field in.

​
Adding Custom Field Values

Once your custom field definition has been created, you can enter values in a few different ways:

​
Individually in the Admin Dashboard

First, navigate to the relevant record (e.g., Product, Order, Fulfillment). Spree Commerce custom field values Open the Custom fields card on the record, or use the three-dot menu in the top right corner. Adding custom field values in Spree Enter the desired values in the form and click Save to finalize your changes. Product custom fields in Spree This works for any individual record type and is perfect for adding or editing a few custom fields manually.
To make a field appear on a product form automatically, add it to a product type.

​
In Bulk (Products Only)

Product custom fields can also be imported or updated in bulk by:
  1. Adding columns to your CSV file using this format: custom_field.<namespace>.<key> (e.g. custom_field.custom.material)
  2. Entering the desired values for each product row.
  3. Importing the file when uploading a new product catalog
You can also update your existing catalog by exporting the product file, updating it as described above, and then reimporting it to apply custom field updates. This is ideal for large-scale changes across multiple products, especially when onboarding a large catalog.
The import template you download is generated for your store, and already ends with one column per custom field you have defined for products. See Import File Template.