@spree/docs 0.1.305 → 0.1.306

package/dist/api-reference/store.yaml

@@ -11854,50 +11854,21 @@ components:
       - id
       - name
       - code
-    PreferenceField:
+    PreferenceSchema:
       type: object
-      description: A single configurable preference on a payment method, promotion
-        rule/action, or calculator. The frontend uses `type` + `default` to render
-        a sensible input.
-      properties:
-        key:
-          type: string
-          example: amount_min
-        type:
-          type: string
-          example: decimal
-          description: string | text | password | integer | decimal | boolean | array
-            | hash
-        default:
-          description: Default value (any JSON type), null when there is no default
-          nullable: true
-      required:
-      - key
-      - type
-    PromotionActionCalculator:
-      type: object
-      description: The action's nested calculator (when the action carries one — null
-        for actions like `free_shipping`)
-      properties:
-        type:
-          type: string
-          example: flat_rate
-          description: Wire shorthand for the calculator subclass
-        label:
-          type: string
-          example: Flat Rate
-        preferences:
-          type: object
-          additionalProperties: true
-        preference_schema:
-          type: array
-          items:
-            "$ref": "#/components/schemas/PreferenceField"
-      required:
-      - type
-      - label
-      - preferences
-      - preference_schema
+      description: 'The JSON Schema (draft 2020-12) of a type''s `preferences`: one
+        property per setting, with `format` (`money`, `currency`, `iso-country`, `prefixed-id`,
+        …), `enum`, `default`, `x-spree-secret` for a secret and `x-spree-prefix`
+        for an id list. Unknown keys are refused.'
+      additionalProperties: true
+      example:
+        type: object
+        properties:
+          amount:
+            type: string
+            format: money
+            default: '0.0'
+        additionalProperties: false
     PromotionActionLineItem:
       type: object
       description: One row in a `create_line_items` action — the variant added to

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

@@ -94,8 +94,8 @@ const calculators = await adminClient.deliveryMethods.calculators()
 await adminClient.deliveryMethods.create({
   name: 'Standard shipping',
   delivery_zone_id: 'dz_xxx',
-  calculator_type: 'flat_rate',
-  calculator_attributes: {
+  calculator: {
+    type: 'flat_rate',
     preferences: { amount: '7.00', currency: 'USD' },
   },
 })

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

@@ -38,7 +38,7 @@ erDiagram
 | `default` | Exactly one channel per store is the default. Used as a fallback when no channel header is present and as the auto-publish target for new products | `true` |
 | `storefront_access` | Controls what an anonymous visitor may see: `public`, `prices_hidden`, or `login_required`. Unset inherits the store's setting. See [Storefront Access Gating](#storefront-access-gating) | `login_required` |
 | `guest_checkout` | Whether an order may be placed without an account on this channel. Unset inherits the store's setting | `false` |
-| `preferred_order_routing_strategy` | Optional per-channel override of the store's [Order Routing](../how-to/custom-order-routing.md) strategy | `rules` |
+| `order_routing_strategy` | Optional per-channel override of the store's [Order Routing](../how-to/custom-order-routing.md) strategy | `rules` |
 
 `code` is normalized to a URL-safe slug on save — `POS` becomes `pos`, `Point of Sale!` becomes `point-of-sale`. Leaving `code` blank derives it from `name`.
 
@@ -132,13 +132,13 @@ Both controls fall back to the owning [Store](stores.md) when the channel's own
 ```typescript Admin SDK
 // Gate a channel behind sign-in, and require accounts at checkout
 await adminClient.channels.update('ch_wholesale', {
-  preferred_storefront_access: 'login_required',
-  preferred_guest_checkout: false,
+  storefront_access: 'login_required',
+  guest_checkout: false,
 })
 
 // Clear the channel value to inherit the store's default
 await adminClient.channels.update('ch_wholesale', {
-  preferred_storefront_access: null,
+  storefront_access: null,
 })
 ```
 
@@ -146,7 +146,7 @@ await adminClient.channels.update('ch_wholesale', {
 curl -X PATCH 'https://api.mystore.com/api/v3/admin/channels/ch_wholesale' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "preferred_storefront_access": "login_required", "preferred_guest_checkout": false }'
+  -d '{ "storefront_access": "login_required", "guest_checkout": false }'
 ```
 
 

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

@@ -295,14 +295,14 @@ Price history tracking is enabled by default. To disable it (e.g., for non-EU st
 
 
 ```typescript Admin SDK
-await client.store.update({ preferred_track_price_history: false })
+await client.store.update({ track_price_history: false })
 ```
 
 ```bash cURL
 curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "preferred_track_price_history": false }'
+  -d '{ "track_price_history": false }'
 ```
 
 

package/dist/developer/customization/model-preferences.md

@@ -39,6 +39,137 @@ end
 
 Any model inheriting from `Spree.base_class` can declare preferences — the reader and writer methods come with it, so there is nothing to include. The values live in that model's `preferences` column.
 
+### Declaring the full type
+
+A declaration is also the preference's contract in the API: Spree turns it into a JSON Schema that the API publishes, the SDKs type and every write is checked against. So a declaration states everything a client needs to know about the value:
+
+```ruby server/app/models/my_app/promotion/rules/loyalty_tier.rb
+module MyApp
+  module Promotion
+    module Rules
+      class LoyaltyTier < Spree::PromotionRule
+        preference :minimum_spend, :money, default: 0
+        preference :tier,          :string, choices: %w[silver gold platinum], default: 'silver'
+        preference :channel_ids,   :array, of: :id, model: 'Spree::Channel', default: [],
+                                   scope: ->(rule) { rule.promotion.store.channels }
+        preference :country_codes, :array, of: :string, format: :iso_country, default: []
+        preference :bonus_amounts, :hash, keys: :currency, values: :money, default: {}
+      end
+    end
+  end
+end
+```
+
+| Option | Applies to | What it says |
+|---|---|---|
+| `of:` | `:array` | The type of each item: `:string`, `:integer`, `:decimal`, `:money`, `:boolean`, `:id` or `:object` |
+| `properties:` | `of: :object` | The fields of each item, e.g. `{ threshold: :money, value: :decimal }` |
+| `keys:` / `values:` | `:hash` | The type of the keys (`:string` or `:currency`) and of the values |
+| `model:` / `scope:` | `of: :id` | The records the ids point at, and the records they must be found in. The API accepts and returns their prefixed ids (`ch_…`); an id of another model, or one outside the scope, is refused |
+| `format:` | `:string`, list items | `:currency`, `:iso_country`, `:timezone`, `:locale`, `:url` or `:color` |
+| `choices:` | any | The fixed set the value must come from; admin forms show a picker |
+
+Decimals and amounts travel as exact strings (`"9.99"`), never as numbers. An `:array` without `of:`, a `:hash` without `keys:` and `values:`, or the `:any` type still works in Spree 6.0, with a deprecation warning and a schema that accepts any value. Spree 6.1 refuses them.
+
+### Preferences in the API
+
+Configurable types — promotion rules and actions, calculators, payment methods, integrations, and price, delivery, commission and order routing rules — send their settings as a `preferences` object next to their `type`. Each family's `/types` endpoint returns the JSON Schema of every registered type's preferences, extensions included, so a client can render a form for a type it has never seen:
+
+
+```typescript Admin SDK
+const { data } = await adminClient.promotionRules.types()
+const itemTotal = data.find((entry) => entry.type === 'item_total')
+itemTotal.schema.properties.amount_min // { type: 'string', format: 'money', default: '100', … }
+```
+
+```bash cURL
+curl 'https://api.mystore.com/api/v3/admin/promotion_rules/types' \
+  -H 'X-Spree-API-Key: sk_xxx'
+```
+
+
+The SDKs also type the settings of every type Spree ships. `TypedPromotionRule` narrows `preferences` by `type`, and an extension adds its own types to `PromotionRulePreferencesMap` by declaration merging.
+
+A write is checked against the schema before anything is saved. An unknown key, a value of the wrong type, a value outside `choices`, or an id of the wrong model or another store is refused with a `422` whose `code` is `invalid_preferences`; `details` names each failing value by its JSON pointer, such as `/preferences/channel_ids/1`. A secret reads back masked; sending the masked value back keeps the stored secret, and `null` clears it.
+
+### Exposing a setting in the API
+
+Use this when a record has a fixed set of settings that clients edit field by field, as the store, a channel or an import do. A family of types with different settings per type (rules, calculators, payment methods) sends a `preferences` object instead, as described above.
+
+The API names such a setting by its plain name (`featured`), never by the `preferred_` method. It takes three declarations, one per layer, and each layer stays in charge of its own job.
+
+**1. Expose it on the model.** `exposes_preferences` gives each preference a plain reader, writer and predicate:
+
+```ruby server/app/models/spree/brand.rb
+module Spree
+  class Brand < Spree.base_class
+    preference :featured, :boolean, default: false
+    preference :display_name, :string
+
+    exposes_preferences :featured, :display_name
+  end
+end
+```
+
+```ruby
+brand.featured           # same as brand.preferred_featured
+brand.featured = true    # same as brand.preferred_featured = true
+brand.featured?          # true
+```
+
+It refuses a name the model already uses for something else. Errors on `preferred_featured` are reported to API clients as `featured`.
+
+**2. Return it from the serializer.** `preference_attributes` adds every exposed preference, typed from its declaration, so the generated SDK types follow the model. Name some to add only those, or pass `except:` to leave some out:
+
+```ruby server/app/serializers/spree/api/v3/admin/brand_serializer.rb
+module Spree
+  module Api
+    module V3
+      module Admin
+        class BrandSerializer < Spree::Api::V3::BaseSerializer
+          attributes :name, created_at: :iso8601, updated_at: :iso8601
+
+          preference_attributes Spree::Brand
+        end
+      end
+    end
+  end
+end
+```
+
+**3. Accept it in the controller.** Exposing a setting does not make it writable: the controller decides, as for any attribute (see [permitted attributes](api.md#permitted-attributes)):
+
+```ruby server/app/controllers/spree/api/v3/admin/brands_controller.rb
+def resource_permitted_attributes
+  [:name, :featured, :display_name]
+end
+```
+
+The setting is then read and written like a column:
+
+**Admin SDK:**
+
+```typescript
+    const brand = await adminClient.request('PATCH', `/brands/${brandId}`, {
+      body: { featured: true, display_name: 'Wilson' },
+    })
+    brand.featured // true
+    ```
+
+  **cURL:**
+
+```bash
+    curl -X PATCH 'https://api.mystore.com/api/v3/admin/brands/brand_xxx' \
+      -H 'X-Spree-API-Key: sk_xxx' \
+      -H 'Content-Type: application/json' \
+      -d '{ "featured": true, "display_name": "Wilson" }'
+    ```
+
+
+> **NOTE:** The Seller API keeps its own list of what sellers may write, so exposing a setting to operators never makes it writable by sellers.
+
+Strings, integers and booleans are cast the way Rails casts attributes (`"1"`, `"true"` and `"on"` are true; `"42"` is 42). A blank value is `nil` for a `nullable: true` preference, and the type's empty value otherwise.
+
 ## Accessing Model Preferences
 
 Once preferences have been defined for a model, they can be accessed either using the shortcut methods that are generated for each preference or the generic methods that are not specific to a particular preference.
@@ -146,4 +277,3 @@ Around fifty models use preferences, and the pattern is always the same: a famil
 | `Spree::Store`, `Spree::Channel` and `Spree::Market` | Merchant settings — timezone, units, currency behaviour |
 
 This is why preferences exist rather than columns: `Spree::Calculator::FlatRate` and `Spree::Calculator::TieredPercent` are rows in one table with entirely different settings, and neither wants a column the other leaves null.
-* `Spree::Theme`

package/dist/developer/customization/validations.md

@@ -73,7 +73,7 @@ dashboard under **Settings → Store**, or through the Admin API:
 
 ```typescript Admin SDK
 await adminClient.store.update({
-  preferred_address_requires_phone: false,
+  address_requires_phone: false,
 })
 ```
 
@@ -81,7 +81,7 @@ await adminClient.store.update({
 curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
-  -d '{ "preferred_address_requires_phone": false }'
+  -d '{ "address_requires_phone": false }'
 ```
 
 

package/dist/developer/how-to/build-a-b2b-store.md

@@ -467,14 +467,14 @@ The gate is enforced by the Store API, not by the storefront, so a storefront ap
 ```typescript Admin SDK
 // Gate the wholesale channel, and give its shoppers a default agreement
 await adminClient.channels.update('ch_xxx', {
-  preferred_storefront_access: 'login_required',
-  preferred_guest_checkout: false,
+  storefront_access: 'login_required',
+  guest_checkout: false,
   default_catalog_id: 'cat_xxx',
 })
 
 // Or set the fallback for every channel that does not set its own
 await adminClient.store.update({
-  preferred_storefront_access: 'prices_hidden',
+  storefront_access: 'prices_hidden',
 })
 ```
 
@@ -483,8 +483,8 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/channels/ch_xxx' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
-        "preferred_storefront_access": "login_required",
-        "preferred_guest_checkout": false,
+        "storefront_access": "login_required",
+        "guest_checkout": false,
         "default_catalog_id": "cat_xxx"
       }'
 ```

package/dist/developer/how-to/build-a-marketplace.md

@@ -50,15 +50,15 @@ Three store preferences decide how sellers get paid. All three are writable thro
 
 | Preference | Default | What it decides |
 |---|---|---|
-| `preferred_payout_provider` | blank | Who moves the money. Blank means core's record-only provider: the ledger is kept correctly and the operator settles by hand. |
-| `preferred_default_payouts_schedule_interval` | `monthly` | How often sellers are settled. One of `daily`, `weekly`, `biweekly`, `monthly`, `manual`. A seller can carry its own interval, which wins. |
-| `preferred_default_minimum_payout_amount` | `0` | What a seller's balance must reach before a settlement is worth sending. Below it the balance carries to the next period. |
+| `payout_provider` | blank | Who moves the money. Blank means core's record-only provider: the ledger is kept correctly and the operator settles by hand. |
+| `default_payouts_schedule_interval` | `monthly` | How often sellers are settled. One of `daily`, `weekly`, `biweekly`, `monthly`, `manual`. A seller can carry its own interval, which wins. |
+| `default_minimum_payout_amount` | `0` | What a seller's balance must reach before a settlement is worth sending. Below it the balance carries to the next period. |
 
 
 ```typescript Admin SDK
 await adminClient.store.update({
-  preferred_default_payouts_schedule_interval: 'weekly',
-  preferred_default_minimum_payout_amount: 25,
+  default_payouts_schedule_interval: 'weekly',
+  default_minimum_payout_amount: '25.00',
 })
 ```
 
@@ -67,8 +67,8 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
-        "preferred_default_payouts_schedule_interval": "weekly",
-        "preferred_default_minimum_payout_amount": 25
+        "default_payouts_schedule_interval": "weekly",
+        "default_minimum_payout_amount": "25.00"
       }'
 ```
 
@@ -88,18 +88,18 @@ Admin API like the payout ones.
 
 | Preference | Default | What it decides |
 |---|---|---|
-| `preferred_auto_approve_sellers` | `false` | Admit a seller the moment they finish the checklist, with nobody looking at them. |
-| `preferred_auto_approve_seller_products` | `false` | Put a seller's product on sale the moment they submit it. |
-| `preferred_send_seller_transactional_emails` | `true` | Whether Spree emails sellers. Turn it off if you front seller communications yourself. |
-| `preferred_default_commission_tax_rate` | `0` | Tax on your commission when neither the rate nor the tax provider names one. |
+| `auto_approve_sellers` | `false` | Admit a seller the moment they finish the checklist, with nobody looking at them. |
+| `auto_approve_seller_products` | `false` | Put a seller's product on sale the moment they submit it. |
+| `send_seller_transactional_emails` | `true` | Whether Spree emails sellers. Turn it off if you front seller communications yourself. |
+| `default_commission_tax_rate` | `0` | Tax on your commission when neither the rate nor the tax provider names one. |
 
 
 ```typescript Admin SDK
 await adminClient.store.update({
-  preferred_auto_approve_sellers: false,
-  preferred_auto_approve_seller_products: false,
-  preferred_send_seller_transactional_emails: true,
-  preferred_default_commission_tax_rate: 0.23,
+  auto_approve_sellers: false,
+  auto_approve_seller_products: false,
+  send_seller_transactional_emails: true,
+  default_commission_tax_rate: '0.23',
 })
 ```
 
@@ -108,10 +108,10 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/store' \
   -H 'X-Spree-API-Key: sk_xxx' \
   -H 'Content-Type: application/json' \
   -d '{
-        "preferred_auto_approve_sellers": false,
-        "preferred_auto_approve_seller_products": false,
-        "preferred_send_seller_transactional_emails": true,
-        "preferred_default_commission_tax_rate": 0.23
+        "auto_approve_sellers": false,
+        "auto_approve_seller_products": false,
+        "send_seller_transactional_emails": true,
+        "default_commission_tax_rate": "0.23"
       }'
 ```
 
@@ -402,7 +402,7 @@ curl -X PATCH 'https://api.mystore.com/api/v3/admin/products/prod_xxx/reject' \
 
 Filter the review queue with a Ransack query on status: `adminClient.products.list({ status_eq: 'proposed' })`.
 
-With `preferred_auto_approve_seller_products` on, submitting chains straight into approval. The submission row still gets written and carries an `auto_approved` marker, so a blank reviewer reads as "this store does not review listings" rather than as a lost name.
+With `auto_approve_seller_products` on, submitting chains straight into approval. The submission row still gets written and carries an `auto_approved` marker, so a blank reviewer reads as "this store does not review listings" rather than as a lost name.
 
 There is no bulk route onto `active` for sellers, and that is deliberate: reaching it is the operator's decision on one listing at a time.
 
@@ -467,7 +467,7 @@ curl 'https://api.mystore.com/api/v3/admin/commission_lines?q[seller_id_eq]=sel_
 
 There is no write path. Correcting a charge is a reversal, not an edit.
 
-In the EU the fee is a separate supply from the sale, so it is taxed separately — that is what `preferred_default_commission_tax_rate` from step 1 is for, and a rate or a tax provider can name its own.
+In the EU the fee is a separate supply from the sale, so it is taxed separately — that is what `default_commission_tax_rate` from step 1 is for, and a rate or a tax provider can name its own.
 
 **Read more:** [Commissions](../core-concepts/commissions.md) covers the four rule types, gross-versus-net, how delivery is treated, currency floors and caps, and commission tax in full. [Commission rates](/user/sellers/commission-rates) is the operator's screen.
 
@@ -584,7 +584,7 @@ curl -X POST 'https://api.mystore.com/api/v3/admin/sellers/sel_xxx/payouts' \
 
 ### Payout providers
 
-A provider is a stateless class registered in `Spree.payout_providers` and chosen per store with `preferred_payout_provider`.
+A provider is a stateless class registered in `Spree.payout_providers` and chosen per store with `payout_provider`.
 
 | Provider | Moves money? | Completion |
 |---|---|---|

package/dist/developer/how-to/custom-order-routing.md

@@ -246,7 +246,7 @@ Activate on the whole store:
 
 ```ruby
 Spree::Store.default.update!(
-  preferred_order_routing_strategy: 'Acme::Oms::Strategy'
+  order_routing_strategy: 'Acme::Oms::Strategy'
 )
 ```
 
@@ -255,11 +255,11 @@ Override on one channel only:
 ```ruby
 store = Spree::Store.default
 store.channels.find_by(code: 'pos').update!(
-  preferred_order_routing_strategy: 'Acme::Oms::Strategy'
+  order_routing_strategy: 'Acme::Oms::Strategy'
 )
 ```
 
-Resolution order: `channel.preferred_order_routing_strategy` → `store.preferred_order_routing_strategy` → the default `Strategy::Rules`. Only a value pointing to a **registered** `Strategy::Base` subclass is used; anything unset, unregistered, or invalid is skipped, so a misconfiguration (or a strategy you've since unregistered) falls back to the default instead of breaking checkout.
+Resolution order: the channel's `order_routing_strategy` → the store's `order_routing_strategy` → the default `Strategy::Rules`. Only a value pointing to a **registered** `Strategy::Base` subclass is used; anything unset, unregistered, or invalid is skipped, so a misconfiguration (or a strategy you've since unregistered) falls back to the default instead of breaking checkout.
 
 ### Step 3: Test the Strategy
 

package/dist/developer/upgrades/5.6-to-6.0.md

@@ -506,7 +506,34 @@ If your storefront or webhook receiver reads any of these fields, compare agains
 | `payment_source_type` | Store API payment setup sessions, `payment_setup_session.*` webhooks | `Spree::CreditCard` | `credit_card` |
 | `type` | Custom fields on products, variants, categories and collections | `Spree::CustomFields::ShortText` | removed — read `field_type` (`short_text`) |
 
-The Admin API follows the same rule everywhere: providers and strategies (`fulfillment_provider: 'manual'`, `preferred_order_routing_strategy: 'rules'`), custom field definition `resource_type` (`product`, `category`), tag `taggable_type`, the owner and originator types on records, the permission subjects `/me` returns (`product`, `category`), and filters such as `q[type_eq]=orders`. An integration written against the Admin API preview sends and expects these short names; the [Admin SDK](../sdk/admin/resources.md) types list them.
+The Admin API follows the same rule everywhere: providers and strategies (`fulfillment_provider: 'manual'`, `order_routing_strategy: 'rules'`), custom field definition `resource_type` (`product`, `category`), tag `taggable_type`, the owner and originator types on records, the permission subjects `/me` returns (`product`, `category`), and filters such as `q[type_eq]=orders`. An integration written against the Admin API preview sends and expects these short names; the [Admin SDK](../sdk/admin/resources.md) types list them.
+
+## Preferences are typed in the API
+
+Settings no longer reach the Admin and Seller APIs in the shape of Ruby's preference methods. The Store API is not affected.
+
+**Settings use plain names.** Every `preferred_*` field is renamed, on read and on write:
+
+| Resource | Before | After |
+|---|---|---|
+| Store (`/admin/store`) | `preferred_timezone`, `preferred_guest_checkout`, `preferred_storefront_url`, … every `preferred_*` field | `timezone`, `guest_checkout`, `storefront_url`, … the same name without the prefix |
+| Channel | `preferred_storefront_access`, `preferred_guest_checkout`, `preferred_order_routing_strategy` | `storefront_access`, `guest_checkout`, `order_routing_strategy` |
+| Import (Admin and Seller) | `preferred_delimiter` | `delimiter` |
+| Seller profile | `preferred_timezone` | `timezone` |
+
+`order.preferred_stock_location_id` keeps its name: it is an association, not a setting. Validation errors name the field without the prefix too. Writes still accept the old `preferred_*` names until Spree 6.1, with a deprecation warning in the server log; responses only carry the new names. The store's `storefront_url` is the setting as saved, `null` when unset; `url` is the address customer links use. The store's `default_minimum_payout_amount` and `default_commission_tax_rate` are now exact decimal strings (`"0.23"`) instead of numbers.
+
+**`preference_schema` is replaced by `schema`.** Rules, actions, payment methods and integrations no longer carry `preference_schema` on every row. Each family's `/types` endpoint (and the delivery-method and promotion-action calculator lists) returns a `schema` per type instead: the JSON Schema of its `preferences`, with `format`, `enum`, `default` and `x-spree-secret`. Read a row's type, then look up its schema there. `/payment_methods/types` now lists every provider, with `installed: true` on those the store already has, instead of leaving them out.
+
+**Writes are validated.** A `preferences` payload with an unknown key, a value of the wrong type, a value outside the declared choices, or an id of another model or another store is refused with a `422` whose `code` is `invalid_preferences`. `details` names each failing value by its JSON pointer (`/preferences/channel_ids/1`, or `/rules/0/preferences/channel_ids/1` inside a list of rules). Before, unknown keys were silently dropped. Send decimals as strings (`"10.0"`) and record ids as prefixed ids (`ch_…`).
+
+**Id lists read as prefixed ids.** Preferences listing records, such as a rule's `channel_ids` or `customer_group_ids`, now return prefixed ids rather than database ids, the same form a write accepts.
+
+**Delivery methods nest their calculator.** `calculator_type` and `calculator_preferences` are replaced by `calculator: { type, preferences }` on read and write, the shape promotion actions already use. Writes still accept the old two parameters until Spree 6.1, with a deprecation warning; their values follow the new rules (decimals as strings).
+
+A preference marked deprecated, such as a flat rate calculator's `minimum_item_total`, is still accepted on write until its removal, with its deprecation warning, but is not read back.
+
+**For extension authors:** declare every preference's full type (`of:` on arrays, `keys:` and `values:` on hashes, the `:money` type for amounts, `choices:`, `format:`). An incomplete declaration still works in 6.0 with a deprecation warning, and its schema accepts any value. Replace `normalize_id_preference` with `preference :ids, :array, of: :id, model:, scope:`, and `in:` with `choices:`. See [Model preferences](../customization/model-preferences.md#declaring-the-full-type).
 
 ## Every event is declared
 
@@ -582,7 +609,7 @@ Saving or touching a product used to bump the `updated_at` of each of its catego
 
 `Spree::OrderRouting::Strategy::Legacy` — the pre-5.5 escape hatch that delegated straight to `Spree::Stock::Coordinator` and consulted no routing rules — is removed and no longer registered in `Spree.order_routing.strategies`.
 
-A store or channel still carrying `preferred_order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy'` **keeps working**: `Order#order_routing_strategy` ignores unregistered classes, logs a warning, and falls back to `Strategy::Rules`. Clear the stale preference to silence the warning — note that saving such a record now fails validation, since the value is no longer in the registry.
+A store or channel still carrying `order_routing_strategy: 'Spree::OrderRouting::Strategy::Legacy'` **keeps working**: `Order#order_routing_strategy` ignores unregistered classes, logs a warning, and falls back to `Strategy::Rules`. Clear the stale preference to silence the warning — note that saving such a record now fails validation, since the value is no longer in the registry.
 
 `Spree::Stock::Coordinator` itself stays — cart fulfillment building, exchanges, and claims still use it.
 
@@ -800,7 +827,7 @@ Other changes that come with it:
 
 - **Numbers are no longer parsed by locale.** Price, variant, payment, refund, store credit, gift card, discount and fee amounts take a number or a canonical decimal string (`"1234.56"`); any other text raises `Spree::Money::InvalidFormat`, which the API answers with `invalid_money_format`. Before 6.0 they were re-read under the request's language, so a store whose language writes a comma decimal (Dutch, German, French) saved the dashboard's `49.50` as 4950, and an unchanged price grew tenfold on each save. Send canonical decimal strings (`"1234.56"`) and convert localized input in the client. `Spree::LocalizedNumber` still works with a warning until 6.1. If your prices were saved in a comma-decimal store before upgrading, check them.
 - **Rounding follows the currency.** Taxes, percentage discounts, promotion splits and shipping markups round to the currency's own decimal places from the ISO 4217 table: whole yen, three decimals for dinar. Two-decimal currencies are unchanged. Open carts in other currencies may change by less than one minor unit the next time they are recalculated. Placed orders do not change. Spree now gives the Hungarian forint two decimal places, as ISO 4217 does.
-- **Money on the API is written to each currency's decimals.** Every amount in the Store, Admin and Seller APIs, and so in webhook payloads and email variables, is a decimal string with exactly its currency's decimal places: `"10.00"` (was `"10.0"`), `"1000"` in yen (was `"1000.0"`), `"1.500"` in dinar. Unit prices keep up to four decimals. Fields that were JSON numbers are now strings: `cart.order_minimum` and `order_minimum_shortfall`, the product filter price range `min`/`max`, report money metrics and percentages, and the store's `preferred_default_minimum_payout_amount` and `preferred_default_commission_tax_rate`. Clients comparing these strings, or parsing them as numbers, should switch to exact decimal arithmetic; the SDKs export `sumMoney`, `subtractMoney`, `multiplyMoney`, `compareMoney` and `isZeroMoney`.
+- **Money on the API is written to each currency's decimals.** Every amount in the Store, Admin and Seller APIs, and so in webhook payloads and email variables, is a decimal string with exactly its currency's decimal places: `"10.00"` (was `"10.0"`), `"1000"` in yen (was `"1000.0"`), `"1.500"` in dinar. Unit prices keep up to four decimals. Fields that were JSON numbers are now strings: `cart.order_minimum` and `order_minimum_shortfall`, the product filter price range `min`/`max`, report money metrics and percentages, and the store's `default_minimum_payout_amount` and `default_commission_tax_rate`. Clients comparing these strings, or parsing them as numbers, should switch to exact decimal arithmetic; the SDKs export `sumMoney`, `subtractMoney`, `multiplyMoney`, `compareMoney` and `isZeroMoney`.
 - **Admin and Seller writes refuse JSON numbers for money.** Amounts and rates, including those inside `preferences`, must be canonical decimal strings (`"19.99"`). A number, a localized or grouped string, or more decimals than the field holds is answered with `422` and `invalid_money_format`, naming the field.
 - **Amounts may not carry more decimals than they can keep.** Now that the columns hold four decimals, the database no longer rounds away a fraction of a cent, so a payment, refund, store credit, gift card, fee or discount with more decimals than its currency has (`10.0049` dollars) fails validation with `too_many_decimals`. Unit prices and cost prices allow four, tax rates five decimals of the fraction (`rate_percent` `"7.125"`, not `"7.1255"`), and price list percentages three. Round in your own code before saving. A manual order discount's `value` and a commission rate's `value` are read as strictly as other money fields.
 - **The Admin and Seller APIs no longer return `display_*` money fields.** Responses carry the amount (`"29.99"`) with its currency, and the client formats it in the reader's own language. Before 6.0 the server formatted a copy in the request's language, which could disagree with the editable amount beside it. Format with `Intl.NumberFormat` or your platform's equivalent. The Store API, webhook payloads and email templates keep their `display_*` fields, and labels such as `display_name` are unchanged.
@@ -851,6 +878,9 @@ Before 6.0 a cart was an incomplete order, so extensions written for 5.x (paymen
 | `Address#firstname`, `#lastname`, `#zipcode` | `#first_name`, `#last_name`, `#postal_code` (columns renamed) |
 | `Address.normalize_zipcode`, `#normalized_zipcode` | `.normalize_postal_code`, `#normalized_postal_code` |
 | `Order#bill_address_firstname`, `#bill_address_lastname` | `#bill_address_first_name`, `#bill_address_last_name` |
+| `preference … parse_on_set: normalize_id_preference(klass:, scope:)` | `preference …, :array, of: :id, model:, scope:` |
+| `preference …, in: [...]` | `preference …, choices: [...]` |
+| `:array` without `of:`, `:hash` without `keys:`/`values:`, the `:any` type | A complete declaration (see [Model preferences](../customization/model-preferences.md#declaring-the-full-type)) |
 | `OptionType#presentation`, `OptionValue#presentation` | `#label` (column renamed, translations included). Reads and writes on an instance only — `where(presentation:)` and `find_by(presentation:)` raise, because Mobility owns `label` so the bridge cannot be an attribute alias. Query by `label`. |
 | `OptionValue#option_type_presentation` | `#option_type_label` |
 | `q[presentation_cont]` (option type / value filters) | `q[label_cont]` — the Ransack whitelist publishes the column, so the filter key moves with it |

package/dist/integrations/payments/stripe-connect.md

@@ -24,9 +24,9 @@ const { data: providers } = await adminClient.payoutProviders.list()
 // find the row with id 'stripe' — `available` says whether this store can use it
 
 await adminClient.store.update({
-  preferred_payout_provider: 'stripe',
-  preferred_default_payouts_schedule_interval: 'weekly',
-  preferred_default_minimum_payout_amount: 50,
+  payout_provider: 'stripe',
+  default_payouts_schedule_interval: 'weekly',
+  default_minimum_payout_amount: '50.00',
 })
 ```
 
@@ -34,7 +34,7 @@ await adminClient.store.update({
 curl -X PATCH https://your-store.com/api/v3/admin/store \
   -H "X-Spree-API-Key: sk_xxx" \
   -H "Content-Type: application/json" \
-  -d '{"preferred_payout_provider": "stripe", "preferred_default_payouts_schedule_interval": "weekly", "preferred_default_minimum_payout_amount": 50}'
+  -d '{"payout_provider": "stripe", "default_payouts_schedule_interval": "weekly", "default_minimum_payout_amount": "50.00"}'
 ```
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spree/docs",
-  "version": "0.1.305",
+  "version": "0.1.306",
   "description": "Spree Commerce developer documentation for AI agents and local reference",
   "type": "module",
   "license": "CC-BY-4.0",