Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Added the custom fields roadmap plan (V-3731) (#15076)

Damian Legawiec9055801fa70c
diff --git a/docs/plans/5.4-metafield-translations.md b/docs/plans/5.4-metafield-translations.md
index 071f455c2d..f20d8a9c28 100644
--- a/docs/plans/5.4-metafield-translations.md
+++ b/docs/plans/5.4-metafield-translations.md
@@ -6,6 +6,8 @@
**Author:** Damian
**Last updated:** 2026-07-27
+> **Amended 2026-10-06, revised 2026-11-02:** the scope here (labels and text-type values only) is kept and now targets Spree 6.1 as Part 7 of `6.0-6.1-custom-fields-roadmap.md`. The **mechanism is superseded**: writes go only through the resource translations batch endpoint (`5.5-6.0-resource-translations-api.md`), never through embedded `translations` / `label_translations` params; names follow the rename (`label`, `spree_custom_field_*_translations`); and rich text is sanitized text, not ActionText. The `date` and `date_time` types are not translatable.
+
## Summary
Metafields and MetafieldDefinitions do not support translations. Products, Options, and Categories are translatable via Mobility, but custom field values and definition labels are locale-unaware. This plan adds translation support for MetafieldDefinition names (admin labels) and Metafield values (text types only), using Spree's existing Mobility + per-entity translation table pattern.
diff --git a/docs/plans/5.4-search-provider.md b/docs/plans/5.4-search-provider.md
index 3d26a60d59..07a4cc1f29 100644
--- a/docs/plans/5.4-search-provider.md
+++ b/docs/plans/5.4-search-provider.md
@@ -6,6 +6,8 @@
**Author:** Damian + Claude
**Last updated:** 2026-07-19
+> **Amended 2026-10-06:** the "6.0 metafield faceting" item is dropped: custom-field values are not listed as facets with counts in `/store/products/filters`, where option types own faceted navigation. `cf_` filtering and sorting (shipped in 5.6) stay as they are, limited to storefront-visible fields for the storefront since 2026-10-22. See `6.0-6.1-custom-fields-roadmap.md` and decisions.md 2026-10-06.
+
## Summary
Add a pluggable search provider interface (`Spree::SearchProvider::Base`) that abstracts product search, filtering, sorting, and facet aggregation behind a clean contract. The default implementation (`Spree::SearchProvider::Database`) uses standard SQL/ILIKE scopes. Meilisearch is the recommended external provider, using `meilisearch-ruby` (raw client, no model overrides).
@@ -659,7 +661,7 @@ end
- **Don't add new PgSearch scopes.** PgSearch is being removed. Use ILIKE for new search logic.
- **Don't add new search logic to ProductScopes.** New search/filter behavior should be designed for the provider interface.
- **Don't hardcode FiltersAggregator usage in controllers.** It will be wrapped by the provider.
-- **New filterable attributes should use MetafieldDefinition.** Don't add one-off `filterable` columns on other models.
+- ~~**New filterable attributes should use MetafieldDefinition.**~~ **Superseded 2026-10-06:** a merchant-managed product attribute may be a searchable/sortable custom field, a fixed value list is an option type (which owns facets), and a developer-owned attribute is a real column. See `6.0-6.1-custom-fields-roadmap.md`.
## Resolved Questions
diff --git a/docs/plans/5.5-6.0-resource-translations-api.md b/docs/plans/5.5-6.0-resource-translations-api.md
index 67333d8d2c..24592836c2 100644
--- a/docs/plans/5.5-6.0-resource-translations-api.md
+++ b/docs/plans/5.5-6.0-resource-translations-api.md
@@ -348,8 +348,8 @@ All labels go through i18next across every language file in `packages/dashboard/
8. `GET /api/v3/admin/translations` coverage matrix; wire the shipped `Spree::Imports/Exports::ProductTranslations` into the dashboard's import-type registry — no JSON bulk endpoint, and no registry-wide CSV (Key Decision 13; a parameterized `ResourceTranslations` pair stays a follow-up).
9. Dashboard: per-resource translation tab (Surface 1) + centralized Translations page (Surface 2) consuming the above.
-**Phase 3 (6.0) — fold in metafields:**
-10. Per `5.4-metafield-translations.md`, register `MetafieldDefinition` (translatable `name`) and `Metafield` (translatable `value`, text types only) in `Spree.translatable_resources`. They become just-another-registered-resource — the `{locale:{field}}` write shape that plan already committed to is a subset of this contract, so no new endpoint is needed.
+**Phase 3 (6.1 — moved by `6.0-6.1-custom-fields-roadmap.md`, Part 7) — fold in custom fields** (`CustomFieldDefinition#label`, `CustomField#value` for text types; written through the batch endpoint only):
+10. Register `CustomFieldDefinition` (translatable `label`) and `CustomField` (translatable `value`, text types only) in `Spree.translatable_resources`, with the scope from `5.4-metafield-translations.md`. They become just-another-registered-resource, written through the batch endpoint, so no new endpoint is needed; that plan's embedded `translations` / `label_translations` params are not built.
## Constraints on Current Work
diff --git a/docs/plans/6.0-6.1-custom-fields-roadmap.md b/docs/plans/6.0-6.1-custom-fields-roadmap.md
new file mode 100644
index 0000000000..938351b165
--- /dev/null
+++ b/docs/plans/6.0-6.1-custom-fields-roadmap.md
@@ -0,0 +1,416 @@
+# Custom Fields Roadmap
+
+**Status:** In Progress — the storefront visibility fix, values in Admin and Store API responses, and dashboard editing for every routed record type are in. A 6.0.x patch protects definition types; everything else is 6.1.
+**Target:** Spree 6.0.x (a type change on update is ignored, with a deprecation warning), Spree 6.1 (enforcement, checkout capture, date types, validation, emails and webhooks, translations, cleanup)
+**Depends on:** `5.4-6.0-custom-fields-rename.md` (implemented), `6.0-store-scoped-custom-field-definitions.md` (implemented), `6.0-cart-order-split.md` (checkout requirements), `5.5-6.0-resource-translations-api.md` (translation writes), `6.0-typed-webhook-events.md`, `6.0-liquid-mjml-emails.md`
+**Author:** Damian Legawiec
+**Last updated:** 2026-11-02
+**Tracking:** Linear V-3731 · GitHub spree/spree#14821
+
+## Summary
+
+Custom fields let a merchant add a typed, labelled value to a record (a product's "Care instructions", an order's "Delivery date") from the dashboard, without a developer or a deploy. This plan settles what the feature is for, and so what it will and will not grow into. Custom fields are a **merchant-facing** feature, **not** a data modelling system: developers who need relations, reusable content types or structured objects add real tables.
+
+Within that scope there are gaps:
+
+- Admin-only fields leaked through storefront search. This is now fixed.
+- A definition's type can still change under existing values.
+- Shoppers cannot fill a field in at checkout, the request merchants keep raising. A delivery date ends up in untyped cart metadata that the merchant cannot see as a field and the seller who ships the order cannot see at all.
+- There is no date or choice type, and no validation.
+- Values never reach emails, webhooks or translations.
+- Core itself uses custom fields as storage for integration data.
+
+## Key Decisions (do not deviate without discussion)
+
+### Scope
+
+- **Custom fields stay a merchant-facing feature, not a data modelling system** (2026-10-06). The feature serves merchants and staff who cannot change code. Developers extending Spree add columns and tables; coding agents make that cheap, and every model already accepts extension attributes (`additional_permitted_attributes`). None of the following will be built:
+ - reusable structured content types (a merchant-defined schema with its own entries);
+ - references from a custom field to other records (product, variant, collection, customer, file);
+ - file or asset fields;
+ - measurement-unit types (weight, dimension, volume) and money;
+ - general "list of any type" fields;
+ - per-field permissions beyond storefront read and write;
+ - custom-field facets: value lists with product counts in `/store/products/filters`.
+
+ Each of these drags in referential integrity, permissions, cache invalidation and admin pickers, and each is better served by a real table.
+- **A `choice` type exists, but shopper-facing product attributes stay option types** (2026-10-06; revised 2026-11-02). A fixed list of values is needed well beyond products, where option types do not exist: a customer's gender at registration, an order's delivery time slot, a company's industry. So `choice` (one value, or several) is available on every resource, products included, where an admin-only list such as "Warehouse zone: A/B/C" has no option-type equivalent. What it never becomes is a storefront facet: "Material: Cotton (12), Wool (4)" is option type territory, because option types already carry labels, translations, ordering and facets, and the docs steer any product attribute shoppers browse or filter by to option types.
+- **Custom-field filtering stays as shipped in 5.6; facet lists are not added** (2026-10-06). Product filtering and sorting by `cf_` keys stay supported, on the storefront and in the admin, on both search providers, for searchable and sortable definitions. What this plan does not add is listing a field's values with counts in `/store/products/filters`. This replaces the "6.0 metafield faceting" item and the "new filterable attributes use custom fields" constraint in `5.4-search-provider.md`.
+
+### Who stores data in custom fields
+
+- **Custom fields are not where code stores its data, core included** (2026-10-06; core's own usage settled 2026-11-02). An extension that needs data ships its own columns or tables, and `Spree::Metadata` stays the untyped place for integration bookkeeping. Custom fields belong to the merchant. An extension may read them, but it never creates definitions behind the merchant's back.
+
+ Core breaks this rule today, and 6.1 fixes it:
+ - payment gateway errors are stored as `gateway.processing_errors`;
+ - external media URLs are stored as `external.url`;
+ - `6.0-payment-gateways-monorepo.md` plans for Adyen to keep payment references in custom fields.
+
+ All three move to metadata or a real column. The old definitions stay readable for one release, with a deprecation warning, and an upgrade task copies the values.
+
+### Visibility and audiences
+
+- **Admin-only values never reach a storefront surface** (6.0, implemented 2026-10-22). That covers reading, filtering, sorting, text search, sort-option labels and search-engine documents. `storefront_visible: false` means the value cannot affect what a shopper sees, including the order of results.
+- **New definitions are hidden from the storefront unless the merchant asks** (6.1, 2026-11-02). A new migration changes the `storefront_visible` column default to false, which is what the dashboard form already sends. This amends decisions.md "`storefront_visible` boolean (default: true)" for custom field definitions only. Payment and delivery methods keep their default of true, because a method a shopper cannot see is useless, while a field a shopper cannot see is the safe default.
+- **Sellers see the order fields shoppers can write, read-only** (2026-11-02). On a marketplace, the seller who ships the order needs the delivery date or gift message. Fields that are `storefront_writable` are shown to sellers on their order view and are copied to each seller's split order. Admin-only order fields stay hidden, as `6.0-seller-order-management.md` already says for custom fields in general. Which **product** fields sellers see and write is owned by `6.0-seller-product-submission.md`.
+- **Emails carry storefront-visible fields only, staff emails included** (2026-11-02). Order emails get forwarded, printed and pasted into support tickets, and core has no separate staff order serializer: `store_owner_notification_email` uses the same `Spree::Emails::OrderSerializer` as the customer email. Admin-only fields stay in the dashboard.
+
+### Definition types
+
+- **A definition's `field_type` and `resource_type` are fixed once it is created** (2026-10-06; rollout settled 2026-11-02). Rollout follows the Admin API's deprecate-first rule, which applies since the 6.0.0 release (`6.0-beta-release.md`):
+ - **6.0.x patch:** an update that sends a different `field_type` or `resource_type` keeps the stored value, logs a deprecation warning and answers as before. Values are protected from that release on.
+ - **6.1:** the model rejects the change with a validation error, so the API answers 422 with a message naming the field. Both attributes become create-only in `request_params`. A client that thinks it changed the type learns that it did not.
+
+ The dashboard already disables both pickers when editing. Changing a type means creating a new definition and moving the values deliberately.
+
+### Storage and validation
+
+- **Storage stays one `text` value per field** (2026-10-06). New types serialize into the existing `value` column, so no new value columns are added. Date and date-time values are ISO 8601 strings, which sort correctly as text.
+- **Validation rules live in one `validations` JSON column on the definition and are enforced in `Spree::CustomField`** (6.1, 2026-10-06).
+ - Enforcing them in `Spree::CustomField` covers every write path at once: Admin API, Seller API, nested attributes, `set_custom_field` and CSV imports.
+ - Rules are checked on **new writes only**: a value that was valid before a rule changed stays readable, and only fails when it is written again.
+ - A new kind of rule needs no migration.
+ - Rules are never queried in SQL.
+- **No regular-expression rules** (2026-10-06). Each pattern is a denial-of-service risk on every write (catastrophic backtracking), and failures produce poor error messages. Length and range cover the merchant cases we have seen.
+- **`required` is enforced where a shopper writes the field, and is advisory everywhere else** (2026-10-06; mechanism corrected 2026-11-02).
+ - A required order field that shoppers can write is a **checkout requirement**. It is declared in `Spree::Checkout::DefaultRequirements`, like `po_number_required`, so the cart's `requirements` list and the completion gate can never disagree (`6.0-cart-order-split.md`, "one completion truth"). It is not a `carts.complete.validate` hook, which would only fail at the end.
+ - A required customer field that shoppers can write is checked at registration and on account update (Part 3), because each is a single shopper write that the server can check as a whole.
+ - Everywhere else (products, categories, and staff or API writes to customers and orders), `required` is a dashboard marker plus a client-side check. The Admin API and CSV import accept a blank value. This keeps decisions.md 2026-08-06: a product and its custom fields are written in two steps, so a rule checked on save breaks the importer or leaves records permanently failing it.
+ - **Accepted trade-off:** an API client can save a product without a required value. A product type's `required` flag and a definition's `required` rule both stay advisory, and the dashboard marks a field when either says so.
+ - **Separate mechanism:** the seller requirement `RequiredCustomFields` (`6.0-seller-onboarding-requirements.md`) is unaffected. It gates seller approval on chosen definitions having values, which is a workflow of its own, and `validations.required` neither feeds nor replaces it.
+
+### Shopper writes
+
+- **Shopper write access is a separate `storefront_writable` boolean** (6.1, 2026-10-06). It sits next to `storefront_visible`, not merged into a three-state column. It is purely additive, and avoids a second breaking change to definition payloads straight after `display_on` became `storefront_visible`.
+ - **Accepted trade-off:** two booleans can express an invalid combination (writable but not visible), so a validation on the definition rejects it.
+- **Shoppers write order and customer fields in 6.1** (2026-10-06; customers added 2026-11-02). Order fields are captured at checkout, customer fields at registration and from the shopper's account. The following are deferred:
+ - **Line-item fields.** Engraving-style input per line keeps using line item `metadata`, which already copies to order lines.
+ - **Company fields.** The Store company endpoint in `6.0-b2b-companies-and-catalogs.md` lists "custom fields" but never accepted them. That plan is being revised in the business-to-business storefront work, which makes company self-registration an Enterprise feature.
+
+## Design Details
+
+### Already in (October 2026)
+
+**Storefront visibility.** Commits 96f24f1716 and e7c603ecda:
+- `Spree::SearchProvider::CustomFieldSchema` (`app/services`) takes an `audience:`, and for `:store` reads only storefront-visible definitions.
+- `Product.search(query, store, audience:)` does the same.
+- Meilisearch index settings always use the storefront schema, and documents carry only storefront-visible values.
+
+**Values in API responses.** `BaseSerializer.expandable_custom_fields` adds an opt-in `expand=custom_fields`. The Store API returns storefront-visible values; the Admin API, with `admin: true`, returns all of them.
+- It is wired on 24 resources in both APIs, orders and customers included.
+- It is **not** wired on carts, nor on these registered resources: Exchange, ProductType, Promotion, PurchaseOrder, Refund, StockLevel, StockTransfer, Store and TaxRate (see Part 8).
+
+**Dashboard editing (#14939).** Every Admin route with the `custom_fieldable` concern has an editor: 20 resources, products through orders.
+
+**Registry.** `Spree::Company` and `Spree::PurchaseOrder` are registered resources.
+
+### Part 1 (6.0.x, then 6.1): definition types are fixed
+
+**6.0.x patch**
+- `Admin::CustomFieldDefinitionsController#update` drops `field_type` and `resource_type` from the attributes it assigns.
+- When either was sent with a value different from the stored one, it logs a deprecation warning naming the attribute and the 6.1 behavior.
+- The response is unchanged.
+- No migration and no model change, so this is safe in a patch release.
+
+**6.1**
+- `Spree::CustomFieldDefinition` validates that `field_type` and `resource_type` are unchanged on a persisted record. The error uses a full `I18n.t('spree.…')` key added to `spree/core/config/locales/en.yml`.
+- An explicit validation is used rather than `attr_readonly`, because what `attr_readonly` does on assignment depends on the host's `raise_on_assign_to_attr_readonly` setting: it either raises (a 500 response) or silently skips.
+- `request_params` declares both attributes `only: :create`, so the update body documents and permits neither. The generated SDK update type and the MCP update tool drop them with it.
+- The controller still checks the raw params, so a client that sends either attribute on update gets the 422 rather than having it silently dropped by `params.permit`.
+- **Every other update path follows the same rule.** `6.0-cli-configurator.md` reconciles definitions by `(resource_type, namespace, key)` and patches what differs. A type change there must be reported as an error, never applied.
+
+### Part 2 (6.1): hidden from the storefront by default
+
+- A new migration runs `change_column_default :spree_custom_field_definitions, :storefront_visible, from: true, to: false`. The shipped rename migration is never edited.
+- Existing definitions keep their stored value.
+- **Side effect:** definitions that core and extensions create automatically through `set_custom_field("ns.key")` or `ensure_custom_field_definition_exists!` become admin-only. That is the intended outcome; Part 8 removes core's own cases anyway.
+- The upgrade guide states the new default for API clients that create definitions without sending `storefront_visible`.
+
+### Part 3 (6.1): shoppers fill in fields
+
+**The definition**
+- `storefront_writable` is a boolean, default false.
+- Only order and customer definitions can set it.
+- A writable field must also be storefront-visible.
+
+**The cart holds the values until checkout completes**
+- `Spree::Cart` includes `Spree::HasCustomFields` and accepts order definitions. The cart is the order before completion, so a merchant defines one field, not two.
+- `resource_type_must_match_custom_field_definition` gets this single, explicit exception.
+- The auto-create paths (`set_custom_field("ns.key")`, `ensure_custom_field_definition_exists!`) refuse to run on a cart, because they would create a definition for `Spree::Cart`.
+
+**Copying to the order**
+- `Carts::Complete#create_draft_order!` copies the cart's custom-field rows to the order, in the same step that copies `metadata`.
+- On a marketplace, `Spree::Carts::SplitBySeller` copies them to every seller's order, as it does for `metadata` and `po_number`. Without that, split orders lose them.
+
+**The Store API**
+- The shared `CART_FIELDS` request schema in `Store::CartsController` gains `custom_fields`, an array of `{ key, value }`. The write shape mirrors the read shape:
+
+ ```json
+ { "custom_fields": [ { "key": "checkout.delivery_date", "value": "2026-10-12" } ] }
+ ```
+
+- **Keys are looked up, never created.** A key resolves only among the store's writable order definitions; an unknown or non-writable key returns 422.
+- **Partial writes.** A blank value removes the field. Fields the request does not name are left as they are, matching how cart metadata merges.
+- **Number values.** They arrive as canonical decimal strings; the server never parses a number by locale (decisions.md 2026-10-09).
+- **Reading back.** The cart serializer gets `expandable_custom_fields`. The order serializer already has it.
+
+**The storefront's list of fields**
+- `GET /api/v3/store/custom_field_definitions?q[resource_type_eq]=order` returns the writable definitions, with their type, label and validation rules. It never returns anything admin-only.
+- As a Store list endpoint, it follows `6.0-typed-filters.md`:
+ - it declares `resource_type` as a short-name filter;
+ - its integration spec uses `filter_parameters_for`;
+ - it exposes no filter that could reach admin-only definitions.
+- `@spree/sdk` gets both the endpoint and the cart field through generated types. Because Store MCP tools take their parameters from OpenAPI (`6.1-store-mcp-server.md`), a shopping agent sees both too.
+
+**Required checkout fields**
+- `Spree::Checkout::DefaultRequirements` (`spree/core/lib/spree/checkout/default_requirements.rb`) emits one requirement per required writable definition the cart has no value for: `{ step: 'payment', field: '<namespace>.<key>', code: 'custom_field_required', message: }`, with the message from a full `I18n.t('spree.checkout_requirements.…')` key.
+- The `payment` step is the last step before completion, where storefronts collect order details. A storefront that asks earlier, or skips the payment step for a free order, still reads the requirement from the cart's `requirements` list.
+- Like `po_number_missing?`, the requirement is skipped for an order staff key in (`keyed_in_by_staff?`): the field is shopper input, and an admin draft order must not be blocked on it.
+
+**Sellers**
+- The seller order serializer exposes the order's `storefront_writable` fields, read-only.
+- `6.0-seller-order-management.md` is amended accordingly.
+
+**Customers: registration and account**
+- `RegisterParams` (`POST /api/v3/store/customers`) and `UpdateCustomerParams` (`PATCH /api/v3/store/customer`) in `Store::CustomersController` gain the same `custom_fields` array, with the same rules as the cart: keys resolve only among the store's writable customer definitions, never auto-created; a blank value removes the field; fields not named are left alone.
+
+ ```json
+ { "email": "[email protected]", "password": "…", "custom_fields": [ { "key": "profile.gender", "value": "female" } ] }
+ ```
+
+- A required writable customer field missing from a registration returns 422 before the account is created, and the fields are written in the same transaction as the account, so a failed field never leaves an account behind (`custom_fields=` otherwise defers until after the first save). An account update cannot blank a required field.
+- The customer serializer already has `expandable_custom_fields`, so a shopper reads back their own values with `expand=custom_fields`.
+- The Store definitions endpoint answers `q[resource_type_eq]=customer` the same way it answers for orders, so a registration form renders from it.
+- Staff and Admin API writes to customers stay unchecked for `required`, like every other non-shopper path.
+
+### Part 4 (6.1): date and choice types
+
+| Token | Class | Stored as | Rules | Searchable / sortable | Dashboard widget |
+|---|---|---|---|---|---|
+| `date` | `Spree::CustomFields::Date` | `YYYY-MM-DD` | min, max | yes / yes | `<StoreDatePicker>` (date only) |
+| `date_time` | `Spree::CustomFields::DateTime` | ISO 8601 UTC | min, max | yes / yes | `<StoreDatePicker includeTime>` |
+| `choice` | `Spree::CustomFields::Choice` | the chosen value, or a JSON array of values when `multiple` | choices (required), multiple | yes / single-value only | `<Select>`, or a multi-select `<Combobox>` |
+
+**Parsing.** Input is parsed with `iso8601`, never `Time.zone.parse`. A date-time written without a zone means the store's time zone (see the time-zone rules in the root `CLAUDE.md`). Every date-time is stored converted to UTC in one fixed format, and `cf_` filter values and `min`/`max` rules are normalized the same way before comparing, because the text comparison is only correct between strings of the same shape (a bare `2026-10-12` sorts before every `2026-10-12T…` value on that day).
+
+**Choices.** A definition's `validations.choices` is an ordered list of `{ value, label }`. The stored value is the `value`, so relabelling a choice changes no stored data, and labels are translated with the definition (Part 7). Removing or renaming a choice's `value` follows the new-writes-only rule: existing values stay readable and are shown raw until rewritten.
+
+**Where the type list is hardcoded.** There is no type-registration API yet, so adding the three types touches every place that lists types today:
+- `Spree::CustomField::TYPE_TOKENS` and the `FIELD_TYPE_TOKENS` typelize;
+- the engine's `custom_fields.types` list;
+- `SearchCapabilities` (`searchable?` and `sortable?` on each type class);
+- the dashboard's `FIELD_TYPES` and `SEARCHABLE_FIELD_TYPES` in `schemas/custom-field-definition.ts`.
+
+**Filtering and sorting.**
+- `CustomFieldSchema#filter_predicates_for` gains a date branch (`eq gt gteq lt lteq present blank`) and a choice branch (`eq not_eq in present blank`), because today every type that is not a number gets the text predicates. A multiple-choice field matches when any of its values matches.
+- `CustomFieldFilterable#custom_field_value_condition` and `#custom_field_value_expression` compare dates as text. ISO strings order correctly, so no cast is needed.
+- `sort_option_label` gets wording for dates; a single choice sorts by its value.
+- Custom-field choices are never added to `/store/products/filters` facets.
+- The Meilisearch provider filters and sorts dates as strings.
+- `cf_` keys stay outside the typed-filters tables, which publish them only as `custom_fields: true`. Their predicate names (`present`/`blank`) therefore stay the existing `cf_` vocabulary, not the typed-filters `null`/`not_null`.
+
+**Other outputs.** CSV export reads `csv_value`; the choice type overrides it to join several values. The Google feed and the GDPR export read the raw `value`, which is already the ISO string for dates; the choice type's raw value is the stored choice (a JSON array when several), which both must render as the values rather than the array text.
+
+### Part 5 (6.1): validation
+
+The definition gets a `validations` JSON column:
+
+| Key | Applies to | Meaning |
+|---|---|---|
+| `required` | all types | The value cannot be blank. Blocks checkout for writable order fields (Part 3). Everywhere else it is a dashboard marker and a client-side check, and the server accepts a blank value. |
+| `min` / `max` | `short_text`, `long_text` (characters); `number`, `date`, `date_time` (value) | Inclusive bounds |
+| `choices` | `choice` | Ordered list of `{ value, label }`; at least one, values unique |
+| `multiple` | `choice` | Several values allowed (stored as a JSON array) |
+
+**Checking**
+- `Spree::CustomFieldDefinition` checks the rules themselves: only keys that apply to the type, `min` no greater than `max`, and choices present and unique.
+- `Spree::CustomField` checks each value against its definition's rules when the value is written.
+- Errors are normal field errors on `value`, so the dashboards' `mapSpreeErrorsToForm` shows them inline.
+- Messages use full `I18n.t('spree.…')` keys.
+
+**Exposure**
+- Rules appear on the Admin definition serializer, on the Store definitions endpoint (writable fields only) and on the Seller definitions endpoint that `6.0-seller-product-submission.md` adds.
+- Every form validates in the browser with the same rules: dashboard, seller panel, seller onboarding and storefront checkout.
+
+### Part 6 (6.1): values reach emails and webhooks
+
+**Emails**
+- A new `Spree::Emails::CustomFieldSerializer` (a thin subclass of the Store one, as `spree/AGENTS.md` requires for every record an email serializes) emits `key`, `label`, `field_type` and `value`.
+- `Spree::Emails::OrderSerializer` and `Spree::Emails::OrderGroupSerializer` include the storefront-visible values through it, instead of deleting `custom_fields`. The group serializer matters because a split marketplace order confirms from the group.
+- `Spree::Emails::TemplateData` requests the expand.
+- Templates read the values like this:
+
+ ```liquid
+ {% for field in order.custom_fields %}{{ field.label }}: {{ field.value }}{% endfor %}
+ ```
+
+- The default order confirmation, order-group confirmation and store-owner notification templates render custom fields when there are any.
+- **Stores with a customized template.** A store that edited its confirmation keeps its own version, and sees the "updated by Spree" notice (`6.0-email-template-editor.md`). The release notes must say so.
+- Also update `docs/developer/customization/email-variables.mdx` and `packages/dashboard/src/lib/email-template-variables.ts`.
+
+**Webhooks**
+- Order and customer lifecycle events request `expand: ['custom_fields']` through the event serializer parameters in `Spree::Publishable`, so payloads carry storefront-visible values.
+- Payloads stay on Store serializers (decisions.md 2026-09-29), so admin-only fields stay out of webhooks.
+- The generated `@spree/sdk/webhooks` types change, and the upgrade guide lists the new payload field.
+
+**No event per value change**
+- `Spree::CustomField` publishes no events of its own.
+- A value change `touch`es the owning record, but a touch-only update publishes no update event either, so editing only a custom field sends no webhook. This is accepted for 6.1: integrations read values with the order or customer events they already receive.
+
+### Part 7 (6.1): translations
+
+**What is translatable**
+- Definition `label`, and each choice's `label`;
+- `short_text`, `long_text` and `rich_text` values;
+- **not** `number`, `boolean`, `json`, `date`, `date_time` or `choice` values (a choice stores its `value`; its label is translated on the definition).
+
+**How**
+- This follows the shipped resource translations contract (`5.5-6.0-resource-translations-api.md`), **not** the embedded `translations` / `label_translations` parameters sketched in `5.4-metafield-translations.md`, which that contract forbids.
+- `Spree::CustomFieldDefinition` and `Spree::CustomField` are added to `Spree.translatable_resources` with Mobility, and declare a `translation_write_permission`.
+- Translations are read through the nested `translations` index and written only through `POST /api/v3/admin/translations/batch`.
+- Translation tables are named `spree_custom_field_definition_translations` and `spree_custom_field_translations`.
+
+**Rich text**
+- Rich-text values are sanitized text since `6.0-rich-text-descriptions.md`, not ActionText.
+- The translation class declares `sanitizes_rich_text` itself, because Mobility translation records do not inherit the model's callbacks.
+
+`5.4-metafield-translations.md` keeps its scope and is superseded on mechanism.
+
+### Part 8 (6.1): cleanup
+
+**Core stops storing data in custom fields**
+- Payment gateway errors move from `gateway.processing_errors` to payment `metadata`.
+- Media external URLs move from `external.url` to a column (or metadata, settled in the implementation pull request).
+- An upgrade task copies existing values and deletes the auto-created definitions, which would otherwise sit in every merchant's list.
+- The old readers keep working for one release, with a deprecation warning.
+- `6.0-payment-gateways-monorepo.md` is amended: Adyen keeps PSP references in payment `metadata`.
+
+**The registry matches what works**
+
+The only source of truth is `Spree.custom_fields.enabled_resources` (`spree/core/lib/spree/core/engine.rb`). Three groups don't match it today:
+
+- **Thirteen registered types have no Admin write path:** Address, Claim, CreditCard, Exchange, LineItem, NewsletterSubscriber, OptionValue, Payment, PaymentSource, Refund, Return, Fulfillment and StockLevel. Only Ruby can write them, yet the definition picker offers them under "Through the API only". Each gets a `custom_fieldable` route, or leaves the registry.
+- **Nine registered types have no `expand=custom_fields`** (listed under "Already in"). Each gets one, or leaves the registry.
+- **Six models include `HasCustomFields` but are not registered,** so no definition can be created for them: Supplier, Channel, Catalog, TaxExemptionCertificate, PaymentSession and PaymentSetupSession. Each gets registered (with a route and an editor), or loses the include.
+
+The `Spree::Metafields` deprecation shell is removed in 6.1 with the other rename bridges.
+
+**Privacy: export and erasure must agree**
+- The customer data export adds order and cart custom fields. Today it exports customer fields only, and metadata only for orders.
+- Anonymization destroys their orders' and carts' custom fields too. Today it destroys only the customer's own fields, and blanks order metadata but not order custom fields.
+- Shopper-entered checkout fields (gift messages, recipient names, delivery instructions) are personal data.
+
+**Other gaps**
+- **N+1 queries.** `expand=custom_fields` on every list endpoint (Admin and Store, plus the new cart and webhook expands) passes the N+1 guard. The list specs that include `'a list without N+1 queries'` request the expand at least once.
+- **Seller onboarding** renders each requirement field with its proper widget, instead of a plain text input (`packages/seller-dashboard/src/pages/onboarding.tsx`).
+- **Customer CSV import** processes `custom_field.*` columns. The template offers them, but `row_processors/customer.rb` ignores them.
+
+**Docs**
+- The 5.6→6.0 upgrade guide lists a "dropdown" custom field, which does not exist in 6.0: change it to name `choice` as a 6.1 type, and point shopper-facing product value lists at option types.
+- Move `docs/developer/core-concepts/metafields.mdx` to `custom-fields.mdx`, with a redirect in `docs/docs.json`.
+
+## Migration Path
+
+**6.0.x patch**
+
+1. Ignore type changes on definition update and log a deprecation warning (Part 1).
+
+**6.1**
+
+2. Migration:
+ - add `storefront_writable` (boolean, default false, `null: false`) and `validations` (JSON) to `spree_custom_field_definitions`;
+ - change the `storefront_visible` default to false.
+3. Type immutability: the model validation, create-only `request_params`, the 422 response, and the configurator rule (Part 1).
+4. The `date`, `date_time` and `choice` types (Part 4).
+5. Validation rules: the definition column, enforcement on the value, Admin, Store and Seller exposure, and every form that edits values (Part 5).
+6. Shopper writes (Part 3): registration and account fields for customers, and checkout capture:
+ - custom fields on the cart;
+ - copying on completion and on seller split;
+ - the Store write and expand;
+ - the Store definitions endpoint;
+ - the checkout requirement;
+ - seller visibility;
+ - SDK types and the storefront checkout.
+7. Emails and webhooks (Part 6). Then regenerate types, Zod schemas and the OpenAPI spec.
+8. Translations (Part 7).
+9. Cleanup (Part 8), including the upgrade task for core's own definitions.
+
+No data migration is needed for existing values. Existing definitions get `storefront_writable: false` and no validation rules, which is exactly how they behave today. Every behavior change ships with a Playwright spec in the admin dashboard, or in the seller panel for seller-facing changes.
+
+## Constraints on Current Work
+
+**Types you must not add**
+
+Do not add a custom field type for any of these:
+- a reference to another record;
+- a file;
+- a measurement unit, or money;
+- a reusable content schema.
+
+Use a column or a table instead, and point the requester to this plan. On products, a value list shoppers browse or filter by is an option type, not a `choice` field.
+
+**Where data belongs**
+- Do not store integration or extension data in custom fields, in core or anywhere else. Extensions own their tables, and `metadata` is for integration bookkeeping.
+
+**Reading and writing**
+- Any code path that reads custom fields for a shopper reads only `storefront_visible: true` values. That includes serializers, search, feeds, webhooks and emails. Search code takes an audience and never assumes admin.
+- Never call `set_custom_field` with a `"ns.key"` string from a Store or Seller API path, and never on a cart. That form auto-creates a definition. API writes resolve existing definitions, or fail.
+- Do not add `field_type` or `resource_type` to any update path: API, import, seeds or configurator.
+- A new type stores its value in the single `value` text column.
+
+**Rules**
+- Custom-field rules do not use regular expressions.
+- Required checkout input is declared as a checkout requirement, never as a completion hook alone.
+
+## Open Questions
+
+All design questions were settled on 2026-10-06 and 2026-11-02. The items below are deferred, not open:
+
+- **Shopper-writable line-item fields.** Waiting on real demand for typed per-line input (engraving, per-item gift notes) that line item metadata does not serve. It also needs a design for limiting a definition to certain products, and for merging fields when cart lines are rebuilt.
+- **Shopper-writable company fields.** Waiting on the revised business-to-business storefront plans. Company self-registration moves to Enterprise.
+- **Server-side `required` outside checkout.** Possible only if products and their custom fields become a single atomic write on every path (Admin API, CSV import, `set_custom_field`). Until then, see decisions.md 2026-08-06.
+- **A type-registration API.** Extension types still fall back to their class name. Waiting on an extension that actually needs a type of its own.
+
+## References
+
+**Custom fields**
+- `5.4-6.0-custom-fields-rename.md`: rename and deprecation bridges (removed in 6.1)
+- `6.0-store-scoped-custom-field-definitions.md`: store-owned definitions, `filter_key`
+- `6.0-product-types.md`: advisory `required` on product types
+
+**Checkout and orders**
+- `6.0-cart-order-split.md`: one completion truth, checkout requirements
+- `6.0-extendable-validations.md`: the completion hooks
+- `6.0-b2b-customer-po-numbers.md`: the pattern Part 3 follows (copy at completion, requirement code, seller split)
+
+**Sellers**
+- `6.0-seller-order-management.md`: what sellers see on orders (amended)
+- `6.0-seller-product-submission.md`: seller-writable product fields
+- `6.0-seller-onboarding-requirements.md`: `RequiredCustomFields`
+
+**Emails and webhooks**
+- `6.0-liquid-mjml-emails.md`, `6.0-email-template-editor.md`: email serializers, variables, customized templates
+- `6.0-typed-webhook-events.md`: payloads on Store serializers
+
+**APIs**
+- `6.0-typed-filters.md`: filters on the new Store endpoint
+- `6.1-store-mcp-server.md`: shopping agents pick up the cart field
+- `6.0-cli-configurator.md`: definitions as code (amended)
+
+**Translations**
+- `5.5-6.0-resource-translations-api.md`: translation writes through the batch endpoint
+- `5.4-metafield-translations.md`: translation scope (superseded on mechanism)
+
+**Search**
+- `5.4-search-provider.md`: `CustomFieldSchema`, Meilisearch (amended)
+
+**Other plans touched**
+- `6.0-payment-gateways-monorepo.md` (amended)
+- `6.0-beta-release.md`: deprecate-first rule after 6.0.0
+
+**Decisions log**
+- decisions.md 2026-08-06 (advisory `required`), 2026-09-29 (webhook payloads), 2026-10-06 (this plan)
+
+**Docs**
+- Developer: `docs/developer/core-concepts/metafields.mdx`
+- User: `docs/user/settings/custom-fields.mdx`
diff --git a/docs/plans/6.0-admin-spa.md b/docs/plans/6.0-admin-spa.md
index 1613874340..546d0dc415 100644
--- a/docs/plans/6.0-admin-spa.md
+++ b/docs/plans/6.0-admin-spa.md
@@ -713,7 +713,7 @@ All drawer-based, opened from `<PageHeader>`'s actions dropdown.
| Component | Backed by |
|---|---|
| `<JsonPreviewDrawer>` | Pretty-prints the resource via Admin SDK serializer + copy-to-clipboard. Replaces `json_previews/show.html.erb`. |
-| `<CustomFieldsDrawer>` | Per-resource custom fields editor. Supports text/longtext/rich_text/number/date/select/json kinds. Depends on the Custom Fields CRUD API in `5.4-6.0-custom-fields-rename.md`. |
+| `<CustomFieldsDrawer>` | Per-resource custom fields editor. Supports short_text/long_text/rich_text/number/boolean/json kinds; `date`, `date_time` and `choice` arrive in 6.1 (`6.0-6.1-custom-fields-roadmap.md`). Depends on the Custom Fields CRUD API in `5.4-6.0-custom-fields-rename.md`. |
| `<TranslationsDrawer>` | Locale tabs + side-by-side editor (see `5.4-centralized-translations-admin.md`). |
| `<AuditLogDrawer>` | Compact timeline of resource changes via the Audit Log API endpoint. |
| `<InternalNoteCard>` | Card with rich text body + edit drawer. Reused for orders, customers, returns. Replaces `shared/_internal_note.html.erb`. |
diff --git a/docs/plans/6.0-cli-configurator.md b/docs/plans/6.0-cli-configurator.md
index 70377f4075..5c1e188994 100644
--- a/docs/plans/6.0-cli-configurator.md
+++ b/docs/plans/6.0-cli-configurator.md
@@ -156,7 +156,9 @@ Where a key is not yet unique in the database, the audit adds the index and vali
4. **Confirm and apply.** Interactive TTY asks once; non-TTY proceeds unless `--fail-on-delete` trips. Writes go through the Admin SDK with idempotency keys, sequentially across sections and in small parallel batches within a section. A 422 is reported against the YAML path of the offending entry with the API's own messages, and the run continues with the remaining entries so one bad row does not hide the rest.
5. **Report.** Counts per section and per outcome; non-zero exit if anything failed.
-Section order follows the reference graph: store, channels, customer groups, tax, delivery zones and profiles, delivery methods, payment methods, stock locations, option types, product types, categories, collections, products (with variants, prices, stock), price lists, custom field definitions, roles, customers, origins, webhooks, integrations, marketplace sections, api keys. Prune runs in reverse order.
+> **Amended 2026-11-02 (`6.0-6.1-custom-fields-roadmap.md`):** custom field definitions come before every section whose records carry custom-field values (products, customers, sellers), so the order below moves them ahead of products. A definition's `field_type` and `resource_type` are fixed once created. `resource_type` is part of the natural key, so an entry whose `resource_type` differs from a live definition's is a different definition: it plans as a create, and the live one is deleted only under `--prune`, like any other unmatched record. A `field_type` that differs on a matched entry is reported as an error in the plan step, never sent as an update. 6.1 adds `storefront_writable` and `validations` to the section schema; against an older instance, an entry that sets either is reported as an error in the plan step and never sent, because the Admin API drops attributes it does not know without an error.
+
+Section order follows the reference graph: store, channels, customer groups, tax, delivery zones and profiles, delivery methods, payment methods, stock locations, option types, product types, categories, collections, custom field definitions, products (with variants, prices, stock), price lists, roles, customers, origins, webhooks, integrations, marketplace sections, api keys. Prune runs in reverse order.
### Introspect
diff --git a/docs/plans/6.0-extendable-validations.md b/docs/plans/6.0-extendable-validations.md
index 337a3a187e..9917aed901 100644
--- a/docs/plans/6.0-extendable-validations.md
+++ b/docs/plans/6.0-extendable-validations.md
@@ -20,8 +20,10 @@ validation of Spree flows**, closes the gaps that undermine that
recommendation, and deliberately does **not** build a generic model-validation
registry. Model-shape rules stay on models: store preferences and the
(newly documented) Address validator registry for core knobs, additive
-decorators as the last resort, and custom fields for new attributes — whose own
-value validation is a deferred, separate topic.
+decorators as the last resort, and custom fields for new merchant-managed
+attributes (an extension's own data goes in its own columns, per
+`6.0-6.1-custom-fields-roadmap.md`) — whose own value validation is a
+deferred, separate topic.
## Key Decisions (do not deviate without discussion)
@@ -122,6 +124,14 @@ value validation is a deferred, separate topic.
where all three write paths converge, gating **new writes only**. The
standing "required stays advisory — never a model validation" constraint
(decisions.md 2026-08-06) is untouched.
+ **Amended 2026-10-06:** designed in `6.0-6.1-custom-fields-roadmap.md`
+ (Part 5) for 6.1: rules in a `validations` JSON column (required, min/max,
+ choices for the `choice` type), **no regex**, and `required` enforced only
+ where a shopper writes the field (amended 2026-11-02): at checkout as a
+ checkout requirement in `Checkout::DefaultRequirements`, not a
+ `carts.complete.validate` hook, so the cart's `requirements` and the
+ completion gate agree; and at customer registration and account update
+ as a 422 from the customer write flow, before the account is created.
## Design Details
diff --git a/docs/plans/6.0-payment-gateways-monorepo.md b/docs/plans/6.0-payment-gateways-monorepo.md
index d0171b9810..2836ddf7fd 100644
--- a/docs/plans/6.0-payment-gateways-monorepo.md
+++ b/docs/plans/6.0-payment-gateways-monorepo.md
@@ -190,6 +190,8 @@ sources):**
- Event processors (authorisation/capture/cancellation), webhook services,
payment sources, presenters, jobs. Adyen stashes PSP references via
`Spree::Metafields` on the payment.
+ **Amended 2026-11-02:** PSP references go in payment `metadata`, never in
+ custom fields, which belong to the merchant (`6.0-6.1-custom-fields-roadmap.md`).
### Drop-set (stays in the old repos)
diff --git a/docs/plans/6.0-seller-order-management.md b/docs/plans/6.0-seller-order-management.md
index eaaade40d6..3a7a5f96f3 100644
--- a/docs/plans/6.0-seller-order-management.md
+++ b/docs/plans/6.0-seller-order-management.md
@@ -68,6 +68,8 @@ The order page becomes the same two-column `ResourceLayout` the dashboard uses,
| Payments, tax lines, discounts, fees | no | the marketplace's money surface |
| Purchase order, internal note, tags, marketplace card, digital links, custom fields, metadata | no | operator bookkeeping |
+> **Amended 2026-11-02:** order custom fields that shoppers can write at checkout (`storefront_writable`, 6.1) are the exception: sellers see them read-only on their order view, and they are copied to each seller's split order, because the seller who ships needs the delivery date or gift message. Admin-only custom fields stay hidden. See `6.0-6.1-custom-fields-roadmap.md` (Part 3).
+
The panel keeps composing from `@spree/dashboard-ui` and `@spree/dashboard-core` and does **not** import from `@spree/dashboard` — the operator app is not a library, and its components are wired to `adminClient`. Where a component is genuinely identical modulo its SDK, it is reimplemented against `sellerClient()` rather than parameterised across the two, because the two clients return different types and a shared generic component would have to be generic over both.
### 3. The customer's email stays hidden, and no new endpoint may leak it
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index 7e33282027..7ff370271a 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -1,3 +1,13 @@
+## 2026-10-06: Custom fields stay a merchant-facing feature, not a data modelling system
+
+**Context:** Custom fields were heading toward a general-purpose schema (record references, files, value lists, reusable content types) while basic gaps went unfixed: admin-only fields leaked through storefront search, a definition's type can change under existing values, shoppers cannot fill a field in at checkout, and core itself stores integration data in auto-created definitions. Revised 2026-11-02 after a review against the code and the plans written since, with 6.0.0 already released.
+
+**Decision:** Custom fields serve merchants who cannot change code: typed, labelled values on a record, shown on or captured from the storefront. Developers and extensions — core included — store their data in real columns, tables or `metadata`, never in custom fields; core's `gateway.processing_errors` and `external.url` move out in 6.1. No custom field type will be added for references, files, measurement units, money, general lists or reusable content types, and no custom-field facets are added; `cf_` filtering and sorting stay. A `choice` type is added for every resource (customers, orders and companies have no option types), but shopper-facing product value lists stay option types. Admin-only values stay off every storefront surface (done 2026-10-22), and emails carry storefront-visible fields only. A definition's `field_type` and `resource_type` are fixed once created: a 6.0.x patch ignores a change with a deprecation warning, 6.1 rejects it with 422. In 6.1: new definitions default to hidden from the storefront; order and customer fields can be `storefront_writable` — order fields held on the cart, copied to the order and to every seller split order, and shown read-only to sellers; customer fields written at registration and from the account; `date`, `date_time` and `choice` types; a `validations` JSON column (required, min/max, choices; no regular expressions) enforced in `Spree::CustomField` on new writes; values in emails and order/customer webhooks; label and text-value translations through the resource translations batch endpoint. `required` is enforced where a shopper writes — a checkout requirement for orders, a 422 at customer registration and account update — and stays advisory elsewhere (2026-08-06). Line-item and company shopper writes are deferred.
+
+**Consequences:** Every shopper-facing read filters `storefront_visible: true`. API writes resolve existing definitions and never auto-create them. Required checkout input is a checkout requirement, never only a completion hook. No update path (API, import, configurator) may change a definition's type. See `6.0-6.1-custom-fields-roadmap.md`.
+
+**Plans amended:** `5.4-metafield-translations.md` (6.1, superseded on mechanism), `5.5-6.0-resource-translations-api.md` (custom-field phase moves to 6.1), `5.4-search-provider.md` (faceting dropped, filterable-attribute constraint superseded), `6.0-extendable-validations.md` (validation designed here; checkout requirement, not hook), `6.0-seller-order-management.md` (sellers see shopper-writable order fields), `6.0-payment-gateways-monorepo.md` (Adyen references in metadata), `6.0-admin-spa.md` (6.1 kinds), `6.0-cli-configurator.md` (section order, no type updates). Amends decisions.md "`storefront_visible` boolean (default: true)" for custom field definitions only.
+
## 2026-10-27: PayPal becomes a provider gem in a 6.0 patch release
**Context:** `spree_paypal_checkout` 0.7.1 does not run on 6.0, so merchants taking PayPal on 5.x cannot upgrade. Its payment-session code predates the cart/order split, `settle_payment!` and money amounts, and several of its behaviours are wrong under 6.0: it stores the capture id as the payment's reference, maps the buyer's approval to an authorization, which in 6.0 would place an order with no money taken, and logs buyer details.