Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Documented how to expose a preference in the API
Damian Legawiecf04e05d475ea
diff --git a/docs/developer/customization/model-preferences.mdx b/docs/developer/customization/model-preferences.mdxindex 32ffe2228d..d1aa8d9f19 100644--- a/docs/developer/customization/model-preferences.mdx+++ b/docs/developer/customization/model-preferences.mdx@@ -94,7 +94,83 @@ The SDKs also type the settings of every type Spree ships. `TypedPromotionRule`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.-Settings of a single resource, such as the store's, are read and written under their plain names (`guest_checkout`, `timezone`), never the `preferred_` methods. A model gives a preference that name with `exposes_preferences :guest_checkout, :timezone`, which defines `guest_checkout`, `guest_checkout=` and `guest_checkout?`; the API controller still lists what it accepts.+### 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](/developer/customization/api#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:++<Tabs>+ <Tab title="Admin SDK">+ ```typescript+ const brand = await adminClient.request('PATCH', `/brands/${brandId}`, {+ body: { featured: true, display_name: 'Wilson' },+ })+ brand.featured // true+ ```+ </Tab>+ <Tab title="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" }'+ ```+ </Tab>+</Tabs>++<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.+</Note>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.