Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Metafields
description: Add custom structured data to products, orders, and other resources with type-safe metafields
canonical: "https://spreecommerce.org/docs/developer/core-concepts/metafields"
---
import { Since } from '/snippets/since.mdx';
<Since version="5.2" />
## Overview
Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike [metadata](/v5/developer/customization/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
```mermaid
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
}
```
```mermaid
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
| Type | Description | Example Values |
|------|-------------|----------------|
| Short Text | Brief text fields | SKU codes, brand names, tags |
| Long Text | Longer text content | Care instructions, notes |
| Rich Text | Formatted HTML content | Product descriptions with formatting |
| Number | Numeric values | Weight, quantity, ratings |
| Boolean | True/false flags | Is featured, requires signature |
| JSON | Structured data | Configuration, complex objects |
## Visibility Control
Metafields support two visibility levels via the `display_on` attribute:
| Visibility | Store API | Admin API | Use Case |
|------------|:---------:|:---------:|----------|
| `both` | Yes | Yes | Public product specifications |
| `back_end` | No | Yes | Internal notes, integration IDs |
## Search, sort & filter
Product metafield definitions can opt into SearchProvider participation:
| Flag | Effect | Allowed field types |
|------|--------|---------------------|
| `searchable` | Values are included in product text search | `short_text`, `long_text`, `number` |
| `sortable` | Listings can sort with `sort=cf_{namespace}_{key}` (prefix `-` for descending), e.g. `cf_custom_label` | `short_text`, `number` |
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
```
| Field type | Predicates |
|------------|------------|
| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
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.
<Info>
Custom resources can also support metafields. See the [Customization Quickstart](/v5/developer/customization/quickstart) for details.
</Info>
## Namespaces
Namespaces organize metafields into logical groups and prevent key conflicts:
| Namespace | Example Keys | Purpose |
|-----------|-------------|---------|
| `properties` | `manufacturer`, `material`, `fit` | Product specifications |
| `shopify` | `product_id`, `variant_id` | Integration data |
| `flags` | `featured`, `requires_approval` | Feature flags |
| `custom` | `gift_message`, `delivery_notes` | Business-specific fields |
<Info>
Namespace and key are automatically normalized to snake_case.
</Info>
## Store API
Metafields with `display_on` set to `both` are included in Store API responses when you [request the `custom_fields` expand](/api-reference/store-api/relations):
<Info>
Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
</Info>
<CodeGroup>
```typescript Store SDK
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"
})
```
```typescript Admin SDK
const product = await adminClient.products.get('prod_86Rf07xd4z', {
expand: ['custom_fields'],
})
```
```bash cURL
curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fields' \
-H 'X-Spree-Api-Key: pk_xxx'
```
</CodeGroup>
**Response:**
```json
{
"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"
}
]
}
```
<Note>
The `display_on` attribute is intentionally excluded from Store API responses for security.
</Note>
## 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](/api-reference/admin-api/endpoints). `storefront_visible: true` is equivalent to `display_on: both` — it exposes the field to the Store API:
<CodeGroup>
```typescript Admin SDK
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)
```
```bash CLI
spree api post /custom_field_definitions -d '{
"resource_type": "Spree::Product",
"namespace": "properties",
"key": "manufacturer",
"label": "Manufacturer",
"field_type": "short_text",
"storefront_visible": true
}'
```
</CodeGroup>
### 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):
<CodeGroup>
```typescript Admin SDK
await client.products.customFields.create('prod_xxx', {
custom_field_definition_id: 'cfdef_xxx',
value: 'Wilson',
})
```
```bash CLI
spree api post /products/prod_xxx/custom_fields -d '{
"custom_field_definition_id": "cfdef_xxx",
"value": "Wilson"
}'
```
</CodeGroup>
## 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.
| Feature | Metafields | [Metadata](/v5/developer/customization/metadata) |
|---------|-----------|----------|
| **Purpose** | Merchant-defined structured attributes | Developer escape hatch — integration IDs, sync state |
| **Schema** | Defined via MetafieldDefinitions | Schemaless JSON — no definition required |
| **Validation** | Type-specific (text, number, boolean, etc.) | None — accepts any JSON-serializable data |
| **Visibility** | Configurable (admin-only or public) | Write-only in Store API, readable in Admin API |
| **Admin UI** | Dedicated management forms | JSON preview |
| **Data Types** | 6 specific types | Any JSON value |
| **Organization** | Namespaced (`namespace.key`) | Flat key-value structure |
| **Queryable** | Via SQL joins, Ransack scopes, search providers | Via JSONB operators (PostgreSQL) |
**Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
**Use [Metadata](/v5/developer/customization/metadata)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
<Warning>
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](/v5/developer/upgrades/5.1-to-5.2#migrate-to-metafields-or-keep-using-product-properties).
</Warning>
## Related Documentation
- [Metadata](/v5/developer/customization/metadata) — Simple key-value metadata
- [Products](/v5/developer/core-concepts/products) — Product catalog
- [Events](/v5/developer/core-concepts/events) — Subscribe to metafield events
- [Admin SDK](/v5/developer/sdk/admin/resources) — Manage definitions and values from TypeScript