@spree/docs 0.1.182 → 0.1.184

package/dist/developer/core-concepts/media.md

@@ -1,16 +1,88 @@
 ---
 title: Media
 sidebarTitle: "Media"
-description: Manage product media in Spree — images, hosted and external video, named variants, focal points, and how media is uploaded, resized, and served via the Store API.
+description: The store-wide media library — uploading once and reusing everywhere, images and video, focal points, and how files are resized and served.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
 ## Overview
 
-Spree handles uploads, processing, and delivery for product media. Images are automatically converted to WebP format and preprocessed into multiple sizes for optimal performance.
+Spree handles uploading, processing and serving the images and video a store shows. Files are converted to WebP and preprocessed into several sizes, so a listing page isn't downloading full-resolution photographs.
+
+Files live in a **store-wide media library**. A file is uploaded once and can then be placed wherever it's needed — on a product, on a category, inside a description — without being uploaded again.
+
+```mermaid
+flowchart LR
+    Upload["Upload once"] --> Library["Media library"]
+    Library --> P["On a product"]
+    Library --> C["On a category"]
+    Library --> D["Inside a description"]
+```
+
+## The media library
+
+Every file in a store is in the library, whether or not it's currently placed on anything. That means a file can be uploaded ahead of time, browsed, searched, and reused.
+
+```typescript Admin SDK
+// Browse everything in the store
+const { data: media } = await adminClient.media.list()
+
+// Where is this file being used?
+const { data: usage } = await adminClient.media.usage('med_xxx')
+```
+
+| Field | What it tells you |
+|---|---|
+| `attached` | Whether the file is placed on anything yet |
+| `filename`, `content_type`, `byte_size` | What the file actually is |
+| `viewable_type` / `viewable_id` | What it's placed on, if anything |
+| `media_type` | `image`, `video` or `external_video` |
+| `alt` | Alt text, for accessibility and SEO |
+| `position` | Order within a gallery |
+
+### Reuse shares the file, not the record
+
+Placing a library file on a product creates a **new media row that shares the same underlying file**:
+
+```typescript Admin SDK
+await adminClient.products.media.create('prod_xxx', {
+  source_media_id: 'med_xxx',
+  alt: 'Worn over a navy jumper',
+  position: 2,
+})
+```
+
+The copy gets its own alt text, its own position, and its own variant links — because the same photograph might be the third image on one product and the hero on another, with different alt text describing what matters in each context. What it doesn't get is a second copy of the bytes.
+
+> **NOTE:** This is why there's no single "shared asset" record to manage. Each placement is independently editable, while storage is shared. Detaching a photo from one product has no effect on any other.
+
+### Deleting, safely
 
-## Product Media
+A file in use can't be deleted by accident:
+
+```typescript Admin SDK
+// Returns 422 with the list of places it's used
+await adminClient.media.delete('med_xxx')
+
+// Remove it from everywhere, then delete
+await adminClient.media.delete('med_xxx', { detach: true })
+```
+
+The dashboard shows you the usage list and asks before doing the second one. Check `usage` before offering a delete in your own tooling.
+
+## What can carry media
+
+| Owner | Typical use |
+|---|---|
+| **Product** | The main gallery |
+| **Variant** | Images specific to one colour or size |
+| **Category** | A banner or tile for a navigation page |
+| **Collection** | The same, for a merchandising group |
+
+Categories and collections also have simple `image` and `square_image` slots. Setting one places the file; clearing it **removes the placement but keeps the file in the library**, so nothing is destroyed by tidying up a page.
+
+Sellers and stores keep their branding as plain attachments — a logo isn't merchandising, and it doesn't belong in a library people browse for product photos.
+
+## Product media
 
 A media record carries:
 
@@ -21,9 +93,9 @@ A media record carries:
 - **Preprocessed named variants** for fast delivery
 - **`variant_ids`** — which product variants the media represents. An empty array means it represents the product as a whole.
 
-### Product-level Gallery 
+### Product-level gallery
 
-In Spree 5.5 the **product** is the default owner of media. Before 5.5, every image was pinned to a specific variant (usually the master), and sharing the same image across variants meant re-uploading the file. From 5.5 onward, an image lives on the product, and any subset of variants can reference it through `variant_ids` — without duplicating the underlying file.
+Media belongs to the **product**, and any subset of its variants can reference the same file through `variant_ids` — so one photograph can represent three colourways without being uploaded three times.
 
 #### Uploading a product-level image
 
@@ -106,7 +178,7 @@ The Store API's `media` field on a product returns its gallery — product-level
 
 This dual rendering means existing storefronts keep working during the upgrade; new uploads attach to the product, and you opt into a [one-shot migration](/v5/developer/upgrades/5.4-to-5.5) to re-home legacy variant-pinned data when convenient.
 
-### Video 
+### Video
 
 A product gallery can hold video as well as images. Spree supports both ways merchants usually have it:
 
@@ -186,7 +258,7 @@ Where the poster comes from, in order:
 
 Spree does not extract a frame from an uploaded video, so give hosted video and Vimeo links a poster if you want them to show a still.
 
-### Focal Point 
+### Focal Point
 
 `focal_point_x` and `focal_point_y` mark the part of an image that must stay in frame when a storefront crops it to a different shape. Both are fractions between 0 and 1, measured from the top left, so `{ x: 0.5, y: 0.5 }` is dead centre — which is also what a storefront should assume when they are null.
 
@@ -199,7 +271,7 @@ await client.products.media.update('prod_86Rf07xd4z', 'media_k5nR8xLq', {
 
 Spree stores the focal point and serves it; the cropping itself is the storefront's decision, since only it knows the shape it needs.
 
-### Named Variant Sizes 
+### Named Variant Sizes
 
 When an image is uploaded, Spree automatically generates optimized versions in the background:
 
@@ -319,15 +391,54 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=media,vari
 | `focal_point_x` | number \| null | Horizontal focal point (0.0–1.0) |
 | `focal_point_y` | number \| null | Vertical focal point (0.0–1.0) |
 | `external_video_url` | string \| null | External video URL (YouTube/Vimeo) |
-| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link  |
-| `video_embed_url` | string \| null | Embeddable player URL, derived from the link  |
-| `video_url` | string \| null | Uploaded video file URL  |
-| `poster_url` | string \| null | Still frame for a video  |
+| `video_provider` | string \| null | `youtube` or `vimeo`, derived from the link |
+| `video_embed_url` | string \| null | Embeddable player URL, derived from the link |
+| `video_url` | string \| null | Uploaded video file URL |
+| `poster_url` | string \| null | Still frame for a video |
 | `original_url` | string \| null | Full-size image URL (inline disposition) |
 | `mini_url` ... `xlarge_url` | string \| null | Named variant URLs |
-| `download_url` | string \| null | Same blob as `original_url` but with `Content-Disposition: attachment`. Admin API only.  |
 
-## Image Processing
+The Admin API adds the fields the library needs:
+
+| Field | Type | Description |
+|---|---|---|
+| `attached` | boolean | Whether the file is placed on anything, or sitting unused in the library |
+| `viewable_type` / `viewable_id` | string \| null | What it's placed on — `product`, `variant`, `category`, `collection` |
+| `filename`, `content_type`, `byte_size` | | What the file actually is |
+| `embed_url` | string \| null | The rendition used inside rich text — sized to fit, not cropped |
+| `signed_id` | string \| null | Lets a plain attachment field adopt this file without re-uploading |
+| `download_url` | string \| null | The same file with `Content-Disposition: attachment` |
+
+> **NOTE:** Two behaviours to expect when rendering a gallery:
+> 
+> **`original_url` is null for any playable video** — there's no still image to size. Use `poster_url`.
+> 
+> **A video's sized URLs come from its poster.** If a video has a poster, every `*_url` resolves from that frame, so a grid of mixed images and video renders uniformly.
+
+## Images in descriptions
+
+Rich text fields — a product description, a category's copy — can carry embedded images. In the dashboard, the editor opens the media library so a merchant picks an existing file or uploads a new one.
+
+Embedded images use their own rendition, sized to fit rather than cropped to a square. A size chart or a diagram keeps its proportions, where a gallery thumbnail would have had its edges cut off.
+
+> **WARNING:** An embedded image is a plain image URL in the HTML — nothing records which description uses which file.
+> 
+> Spree's usage check does its best by searching descriptions for the file, but it can't be exhaustive. Deleting a library file can leave a broken image in a description, so treat the usage list as a warning rather than proof a file is unused.
+
+## Who can manage media
+
+Media is its own permission, separate from products:
+
+| Action | Requires |
+|---|---|
+| A product's own gallery — add, reorder, remove | Permission to edit **products** |
+| Browsing the library, checking usage, deleting a file outright | **Media** permission |
+
+The reasoning: reaching a file through a product you can already edit isn't the same as enumerating every file in the store. Someone who manages one product's photos shouldn't automatically be able to browse — or delete — everything the business has ever uploaded.
+
+Note the asymmetry that follows. Removing an image from a product removes the *placement* and needs only product permission; deleting the file everywhere is a library action and needs the media key.
+
+## Image processing
 
 Spree uses [libvips](https://www.libvips.org/) for image processing. Images are automatically:
 

package/dist/developer/core-concepts/metafields.md

@@ -1,148 +1,125 @@
 ---
-title: Metafields
-description: Add custom structured data to products, orders, and other resources with type-safe metafields
+title: Custom Fields
+description: Add your own structured, typed data to products, orders and other records — searchable, filterable, and editable in the dashboard.
 ---
 
-import { Since } from '/snippets/since.mdx';
-
-
 ## Overview
 
-Metafields provide a flexible, type-safe system for adding custom structured attributes to Spree models. Unlike [metadata](../customization/metadata.md) which is simple JSON storage, metafields are schema-defined with strong typing, validation, and visibility controls.
+Sooner or later you need to store something Spree doesn't have a field for. A fabric composition. A care instruction. A gift message. An ID from the system you sync with.
+
+Custom fields are how you do that without changing the database. You declare a field once — its name, its type, who can see it — and from then on it can be set on any record of that kind, edited in the dashboard, returned by the API, and searched or filtered like any built-in field.
 
-Use metafields for:
+> **NOTE:** Custom fields were called **metafields** before Spree 6.0. The API and SDK have always called them custom fields; now the rest of Spree does too.
 
-- Product specifications (manufacturer, material, dimensions)
-- Custom business logic fields
-- Integration data from external systems
-- Order-specific custom attributes
+## Definitions and values
 
-## Architecture
+There are two halves, and it helps to keep them straight:
 
 ```mermaid
 erDiagram
-    MetafieldDefinition ||--o{ Metafield : "defines schema for"
-    Product ||--o{ Metafield : "has many"
-    Variant ||--o{ Metafield : "has many"
-    Order ||--o{ Metafield : "has many"
+    CustomFieldDefinition ||--o{ CustomField : "gives shape to"
+    Product ||--o{ CustomField : "has values"
+    Order ||--o{ CustomField : "has values"
+    Customer ||--o{ CustomField : "has values"
 
-    MetafieldDefinition {
+    CustomFieldDefinition {
         string namespace
         string key
-        string name
-        string metafield_type
+        string label
+        string field_type
         string resource_type
-        string display_on
+        boolean storefront_visible
         boolean searchable
         boolean sortable
     }
 
-    Metafield {
-        string type
-        text value
-        string resource_type
+    CustomField {
+        string key
+        string label
+        string field_type
+        any value
     }
 ```
 
-```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
+- A **definition** is the declaration: "products have a Material, it is short text, shoppers may see it." You create it once.
+- A **custom field** is one record's answer: this product's material is `100% Cotton`.
 
-| 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 |
+Because the definition carries the type and the label, the dashboard can build an editing form for it automatically, and your storefront gets a value it can trust the shape of.
 
-## Visibility Control
+## Field types
 
-Metafields support two visibility levels via the `display_on` attribute:
+| Type | For | Example |
+|---|---|---|
+| `short_text` | A word or a line | `Wilson`, `100% Cotton` |
+| `long_text` | A paragraph | Care instructions |
+| `rich_text` | Formatted HTML | A spec sheet with lists and bold |
+| `number` | A quantity or measure | `3.5`, `120` |
+| `boolean` | A yes or no | Requires a signature |
+| `json` | Structured data | A sizing chart |
 
-| Visibility | Store API | Admin API | Use Case |
-|------------|:---------:|:---------:|----------|
-| `both` | Yes | Yes | Public product specifications |
-| `back_end` | No | Yes | Internal notes, integration IDs |
+## Who can see it
 
-## Search, sort & filter
+`storefront_visible` decides whether a field ever leaves the back office:
 
-Product metafield definitions can opt into SearchProvider participation:
+| `storefront_visible` | Store API | Admin API | Use it for |
+|---|:---:|:---:|---|
+| `true` | Yes | Yes | Anything a shopper should see — materials, specs |
+| `false` | No | Yes | Internal notes, supplier codes, sync IDs |
 
-| 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` |
+> **WARNING:** `storefront_visible: false` genuinely withholds the field from the Store API — it is not hidden in the response, it is absent. Treat it as the boundary between what a customer may read and what only staff may.
 
-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.
+## Declaring a field
 
-### 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
+```typescript Admin SDK
+const definition = await adminClient.customFieldDefinitions.create({
+  resource_type: 'Spree::Product',
+  namespace: 'properties',
+  key: 'material',
+  label: 'Material',
+  field_type: 'short_text',
+  storefront_visible: true,
+  searchable: true,
+})
 ```
 
-| 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
+```bash CLI
+spree api post /custom_field_definitions -d '{
+  "resource_type": "Spree::Product",
+  "namespace": "properties",
+  "key": "material",
+  "label": "Material",
+  "field_type": "short_text",
+  "storefront_visible": true,
+  "searchable": true
+}'
+```
 
-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](../customization/quickstart.md) for details.
+`namespace` keeps groups of fields apart, so an integration's `product_id` never collides with yours. Together they form the key you'll see in responses: `properties.material`. Both are normalized to snake_case.
 
-## Namespaces
+Definitions can also be managed in the dashboard under **Settings → Custom Fields**, which is where merchants usually add them.
 
-Namespaces organize metafields into logical groups and prevent key conflicts:
+## Setting and reading values
 
-| 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.
+```typescript Admin SDK
+// Set a value on a product
+await adminClient.products.customFields.create('prod_xxx', {
+  custom_field_definition_id: definition.id,
+  value: '100% Cotton',
+})
+```
 
-## Store API
+```bash CLI
+spree api post /products/prod_xxx/custom_fields -d '{
+  "custom_field_definition_id": "cfdef_xxx",
+  "value": "100% Cotton"
+}'
+```
 
-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.md):
 
-> **INFO:** Metafields in API are called Custom Fields as we plan to rename Metafields to Custom Fields completely in Spree 6.0.
+Reading them from a storefront is an expand on whatever you already fetch:
 
 
 ```typescript Store SDK
@@ -150,44 +127,29 @@ 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'],
+product.custom_fields?.forEach((field) => {
+  field.key        // "properties.material"
+  field.label      // "Material"
+  field.value      // "100% Cotton"
+  field.field_type // "short_text"
 })
 ```
 
 ```bash cURL
 curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fields' \
-  -H 'X-Spree-Api-Key: pk_xxx'
+  -H 'X-Spree-API-Key: pk_xxx'
 ```
 
 
-**Response:**
-
-```json
+```json Response
 {
   "id": "prod_86Rf07xd4z",
-  "name": "Spree T-Shirt",
+  "name": "Spree Tote",
   "custom_fields": [
     {
       "id": "cf_k5nR8xLq",
-      "label": "Manufacturer",
-      "key": "properties.manufacturer",
-      "field_type": "short_text",
-      "value": "Wilson"
-    },
-    {
-      "id": "cf_m3Rp9wXz",
-      "label": "Material",
       "key": "properties.material",
+      "label": "Material",
       "field_type": "short_text",
       "value": "100% Cotton"
     }
@@ -195,96 +157,57 @@ curl 'https://api.mystore.com/api/v3/store/products/spree-tote?expand=custom_fie
 }
 ```
 
-> **NOTE:** The `display_on` attribute is intentionally excluded from Store API responses for security.
-
-## Admin Management
-
-### Managing Definitions
+Each value arrives with its own label and type, so you can render a spec table straight from the array without hardcoding which fields exist.
 
-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.
+## Searching, sorting and filtering
 
-Definitions are also [managed via the Admin API](../../api-reference/admin-api/endpoints.md). `storefront_visible: true` is equivalent to `display_on: both` — it exposes the field to the Store API:
+A custom field can take part in product listings — but only if you ask, because indexing everything by default would be wasteful.
 
+| Flag | What it enables | Works with |
+|---|---|---|
+| `searchable` | The value is matched by product text search | `short_text`, `long_text`, `number` |
+| `sortable` | Listings can be ordered by it | `short_text`, `number` |
 
-```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,
-})
+Setting either flag also makes the field **filterable**. Filter and sort with the field's `cf_` key, on both APIs:
 
-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
-}'
+GET /api/v3/store/products?q[cf_properties_material_i_cont]=wool
+GET /api/v3/store/products?sort=-cf_properties_weight
+GET /api/v3/admin/products?q[cf_properties_weight_gteq]=3.5
 ```
 
+| Field type | Comparisons available |
+|---|---|
+| `short_text`, `long_text` | `i_cont`, `cont`, `eq`, `not_eq`, `start`, `end`, `present`, `blank` |
+| `number` | `eq`, `gt`, `gteq`, `lt`, `lteq`, `present`, `blank` |
 
-### 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):
-
-
-```typescript Admin SDK
-await client.products.customFields.create('prod_xxx', {
-  custom_field_definition_id: 'cfdef_xxx',
-  value: 'Wilson',
-})
-```
+Use `i_cont` for case-insensitive matching. A comparison that doesn't suit the field's type is ignored rather than rejected, so a stale filter in a saved view can't break a page.
 
-```bash CLI
-spree api post /products/prod_xxx/custom_fields -d '{
-  "custom_field_definition_id": "cfdef_xxx",
-  "value": "Wilson"
-}'
-```
+> **INFO:** If you use Meilisearch, re-index after changing these flags so the new fields are picked up. Substring matching (`i_cont`, `cont`, `start`, `end`) is a database-provider feature; Meilisearch handles equality, ranges and presence. See [Search & Filtering](search-filtering.md).
 
+In the dashboard, fields with these flags become available in the product table's column picker, sort menu and filter panel — off by default, so merchants opt in per column.
 
-## Metafields vs Metadata
+## What can carry custom fields
 
-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.
+Most things you'd want to annotate: products, variants, orders, line items, customers, categories, payments, fulfillments, gift cards and store credits, among others.
 
-| Feature | Metafields | [Metadata](../customization/metadata.md) |
-|---------|-----------|----------|
-| **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) |
+## Custom fields or metadata?
 
-**Use Metafields** when you need type validation, visibility control, admin UI forms, or organized namespacing.
+Spree has two ways to store your own data, and they are not competing — they solve different problems.
 
-**Use [Metadata](../customization/metadata.md)** for external system IDs, tracking attribution, syncing with integrations, or simple write-and-forget data that only backend systems need to read.
+| | Custom fields | [Metadata](../customization/metadata.md) |
+|---|---|---|
+| **For** | Data a merchant curates | Data your code keeps |
+| **Shape** | Declared and typed | Any JSON, no declaration |
+| **Dashboard** | Proper edit forms | Raw JSON |
+| **Visibility** | Configurable per field | Never read by the Store API |
+| **Searchable** | Yes, opt in | Not through the product search |
 
-> **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).
+Put it simply: **custom fields are for people, metadata is for machines.** If a merchant should type it, define a custom field. If it is a sync token or an external ID that only your integration reads, use metadata.
 
-## Related Documentation
+## Related
 
-- [Metadata](../customization/metadata.md) — Simple key-value metadata
-- [Products](products.md) — Product catalog
-- [Events](events.md) — Subscribe to metafield events
-- [Admin SDK](../sdk/admin/resources.md) — Manage definitions and values from TypeScript
+- [Metadata](../customization/metadata.md) — the machine-readable alternative
+- [Products](products.md) — the most common place for custom fields
+- [Search & Filtering](search-filtering.md) — how filters and search work
+- [Admin SDK](../sdk/admin/resources.md) — managing definitions and values in TypeScript