Metafields

import { Since } from '/snippets/since.mdx';

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

erDiagram
    MetafieldDefinition ||--o{ Metafield : "defines schema for"
    Product ||--o{ Metafield : "has many"
    Variant ||--o{ Metafield : "has many"
    Order ||--o{ Metafield : "has many"

    MetafieldDefinition {
        string namespace
        string key
        string name
        string metafield_type
        string resource_type
        string display_on
        boolean searchable
        boolean sortable
    }

    Metafield {
        string type
        text value
        string resource_type
    }

flowchart LR
    subgraph Definition
        A[MetafieldDefinition] --> B["namespace: properties"]
        A --> C["key: manufacturer"]
        A --> D["type: ShortText"]
        A --> E["resource_type: Product"]
        A --> F["display_on: both"]
    end

    subgraph Instance
        G[Metafield] --> H["value: Wilson"]
        G --> I["resource: Product #1"]
    end

    A -.->|"defines schema"| G

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

Data Types

Visibility Control

Metafields support two visibility levels via the display_on attribute:

Search, sort & filter

Product metafield definitions can opt into SearchProvider participation:

Both default to false. Set them on the definition (Admin UI, Admin API, or seeds). For an existing catalog with Meilisearch, run rake spree:search:reindex after toggling flags so index settings and product documents pick up new cf_* fields.

Filtering

Any definition with either flag set also becomes filterable on product listings, using its cf_* key as a Ransack predicate. The Store and Admin APIs accept the same keys and the same sort values:

GET /api/v3/store/products?q[cf_custom_material_i_cont]=wool
GET /api/v3/admin/products?q[cf_custom_weight_gteq]=3.5
GET /api/v3/store/products?sort=-cf_custom_weight

Use i_cont for case-insensitive matching — plain cont is case-sensitive on PostgreSQL.

Predicates that don't match the definition's field type are ignored rather than rejected, as are keys matching no definition. Meilisearch supports the equality, range, and present/blank predicates; substring predicates (i_cont, cont, start, end) apply only to the database provider.

CSV exports honor the same predicates, so exporting a filtered product list matches what the admin sees.

In the admin dashboard, these fields appear in the products table's column selector, Sort dropdown, and filter panel — hidden by default, so admins opt in per column.

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.

Namespaces

Namespaces organize metafields into logical groups and prevent key conflicts:

Store API

Metafields with display_on set to both are included in Store API responses when you request the custom_fields expand:

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"
})

const product = await adminClient.products.get('prod_86Rf07xd4z', {
  expand: ['custom_fields'],
})

curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fields' \
  -H 'X-Spree-Api-Key: pk_xxx'

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"
    }
  ]
}

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)

spree api post /custom_field_definitions -d '{
  "resource_type": "Spree::Product",
  "namespace": "properties",
  "key": "manufacturer",
  "label": "Manufacturer",
  "field_type": "short_text",
  "storefront_visible": true
}'

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',
})

spree api post /products/prod_xxx/custom_fields -d '{
  "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.

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.

Related Documentation

• Metadata — Simple key-value metadata
• Products — Product catalog
• Events — Subscribe to metafield events
• Admin SDK — Manage definitions and values from TypeScript