Skip to main content

​
Overview

Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike metadata which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls. Use metafields for:
  • Product specifications (manufacturer, material, dimensions)
  • Custom business logic fields
  • Integration data from external systems
  • Order-specific custom attributes

​
Architecture

  • MetafieldDefinition — the blueprint that defines the data type, target resource, and visibility
  • Metafield — stores the actual value for a specific resource instance

​
Data Types

TypeDescriptionExample Values
Short TextBrief text fieldsSKU codes, brand names, tags
Long TextLonger text contentCare instructions, notes
Rich TextFormatted HTML contentProduct descriptions with formatting
NumberNumeric valuesWeight, quantity, ratings
BooleanTrue/false flagsIs featured, requires signature
JSONStructured dataConfiguration, complex objects

​
Visibility Control

Metafields support two visibility levels via the display_on attribute:
VisibilityStore APIAdmin APIUse Case
bothYesYesPublic product specifications
back_endNoYesInternal notes, integration IDs

​
Supported Resources

Metafields can be attached to most Spree resources including Products, Variants, Orders, Line Items, Taxons, Payments, Shipments, Gift Cards, Store Credits, and more.
Custom resources can also support metafields. See the Customization Quickstart for details.

​
Namespaces

Namespaces organize metafields into logical groups and prevent key conflicts:
NamespaceExample KeysPurpose
propertiesmanufacturer, material, fitProduct specifications
shopifyproduct_id, variant_idIntegration data
flagsfeatured, requires_approvalFeature flags
customgift_message, delivery_notesBusiness-specific fields
Namespace and key are automatically normalized to snake_case.

​
Store API

Metafields with display_on set to both are included in Store API responses when you request the custom_fields expand:
Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
const product = await client.products.get('spree-tote', {
  expand: ['custom_fields'],
})

product.custom_fields?.forEach(field => {
  console.log(field.key)   // "properties.manufacturer"
  console.log(field.label) // "Manufacturer"
  console.log(field.value)      // "Wilson"
  console.log(field.field_type) // "short_text"
})
Response: 
{
  "id": "prod_86Rf07xd4z",
  "name": "Spree T-Shirt",
  "custom_fields": [
    {
      "id": "cf_k5nR8xLq",
      "label": "Manufacturer",
      "key": "properties.manufacturer",
      "field_type": "short_text",
      "value": "Wilson"
    },
    {
      "id": "cf_m3Rp9wXz",
      "label": "Material",
      "key": "properties.material",
      "field_type": "short_text",
      "value": "100% Cotton"
    }
  ]
}
The display_on attribute is intentionally excluded from Store API responses for security.

​
Admin Management

​
Managing Definitions

Navigate to Settings → Metafield Definitions in the Admin Panel to create and manage metafield definitions. Select the resource type, enter namespace and key, choose the data type, and set visibility. Definitions are also managed via the Admin API. storefront_visible: true is equivalent to display_on: both — it exposes the field to the Store API: 
import { createAdminClient } from '@spree/admin-sdk'

const client = createAdminClient({
  baseUrl: 'https://store.example.com',
  secretKey: 'sk_xxx',
})

const definition = await client.customFieldDefinitions.create({
  resource_type: 'Spree::Product',
  namespace: 'properties',
  key: 'manufacturer',
  label: 'Manufacturer',
  field_type: 'short_text',
  storefront_visible: true,
})

await client.customFieldDefinitions.update(definition.id, { storefront_visible: false })
await client.customFieldDefinitions.delete(definition.id)

​
Managing Values

When editing a resource (e.g., a product), metafields appear in a dedicated section. The admin panel automatically builds forms for all defined metafields. To set a value programmatically, use the resource’s nested customFields accessor (parent ID first): 
await client.products.customFields.create('prod_xxx', {
  custom_field_definition_id: 'cfdef_xxx',
  value: 'Wilson',
})

​
Metafields vs Metadata

Spree has two permanent, complementary systems for custom data — metadata for machines, metafields for humans. They serve different purposes and are not interchangeable. Neither is going away.
FeatureMetafieldsMetadata
PurposeMerchant-defined structured attributesDeveloper escape hatch — integration IDs, sync state
SchemaDefined via MetafieldDefinitionsSchemaless JSON — no definition required
ValidationType-specific (text, number, boolean, etc.)None — accepts any JSON-serializable data
VisibilityConfigurable (admin-only or public)Write-only in Store API, readable in Admin API
Admin UIDedicated management formsJSON preview
Data Types6 specific typesAny JSON value
OrganizationNamespaced (namespace.key)Flat key-value structure
QueryableVia SQL joins, Ransack scopes, search providersVia JSONB operators (PostgreSQL)
Use Metafields when you need type validation, visibility control, admin UI forms, or organized namespacing. Use Metadata for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
Product Properties are deprecated and will be removed in Spree 6.0. For new projects, always use Metafields. For existing projects, plan to migrate using the migration guide.
  • Metadata — Simple key-value metadata
  • Products — Product catalog
  • Events — Subscribe to metafield events
  • Admin SDK — Manage definitions and values from TypeScript