Spree Decorators

Commands use the Spree CLI (
spree …
). On a classic Rails app without the CLI, use
bin/rails g …
from the app root. Paths assume the Rails app lives in
server/
.

Decorators change existing Spree classes from your app with Ruby's

Module#prepend

, using a Spree filename convention and two generators. They couple you to Spree internals — use them for structural changes (association, validation, scope, read-only helper method, a narrowed controller scope), not for behavior.

Pick the right tool first

Use case	Use this instead of a decorator
Veto an operation (add-to-cart limit, checkout rule, cancel/return policy)	Workflow `validate` hook — `spree-workflows`
Contribute data to tax / promotion calculation	Workflow context hook — `spree-workflows`
Do something alongside a cart/order/fulfillment/payment operation	Workflow lifecycle hook — `spree-workflows`
React after a save / sync to ERP / send notification	Event subscriber — `spree-events-webhooks`
Replace how a flow computes	`Spree.dependencies` — `spree-dependencies`
Change an API response shape	Serializer subclass via `Spree.api.*_serializer` — `spree-dependencies`
Accept an extra attribute on API writes	`Model.additional_permitted_attributes += [...]` (below)
Make a field filterable via `q[...]`	`Spree.ransack.add_attribute(Spree::Product, :brand_id)`
Store an extra value without a migration	Custom fields ( `product.set_custom_field('ns.key', value)` ) — `spree-catalog`
Add a new endpoint	A new `ResourceController` subclass — `spree-resource`
Admin UI changes	Dashboard plugins / slots — `spree-dashboard-plugins`
Add an association, validation, scope, or helper method to a model	Decorator (this skill)
Narrow an existing endpoint's `scope` , swap its `serializer_class`	Controller decorator (this skill)

Never decorate business verbs (

Order#finalize!

Order#cancel

Payment#capture!

Fulfillment#finalize!

): they are deprecated shells that delegate to workflows, and the real flows (

Spree::Carts::Complete

Spree::Orders::Cancel

Spree::Payments::Capture

) don't call them. Status transitions have no state-machine callbacks to hook either — use the workflow's hooks.

The pattern

ruby

# server/app/models/spree/product_decorator.rb
module Spree
  module ProductDecorator
    def self.prepended(base)
      # class-level: associations, validations, scopes, class_attributes — called on base
    end

    # instance methods here; call super to reach the original
  end

  Product.prepend(ProductDecorator)
end

Decorators are loaded by a

config.to_prepare

block in

config/application.rb

(added by the Spree installer) that globs

app/**/*_decorator*.rb

— so

prepend

runs at boot and after every dev reload. If your app lacks that block, add it: Zeitwerk alone never loads an unreferenced decorator and it will silently not apply.

Generators

bash

spree generate model_decorator Spree::Product
# → server/app/models/spree/product_decorator.rb

spree generate controller_decorator Spree::Api::V3::Admin::ProductsController
# → server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb

(

bin/rails g spree:model_decorator …

without the CLI.) The model generator runs the name through

classify

, which singularizes — for plural-named classes (

Spree::Exports::Products

) write the file by hand.

Model decorator patterns

Add an association

Migration first — Spree style is no FK constraint:

bash

spree generate migration AddBrandIdToSpreeProducts brand_id:bigint:index

ruby

class AddBrandIdToSpreeProducts < ActiveRecord::Migration[8.1]
  def change
    add_column :spree_products, :brand_id, :bigint
    add_index :spree_products, :brand_id
  end
end

ruby

module Spree
  module ProductDecorator
    def self.prepended(base)
      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
      base.has_many :videos, class_name: 'Spree::Video', dependent: :destroy
      base.additional_permitted_attributes += [:brand_id]   # writable via Admin API (see below)
    end
  end

  Product.prepend(ProductDecorator)
end

belongs_to

is required by default in Spree models — add

optional: true

or every existing product fails with "Brand must exist". Always pass

class_name

(string — resolved lazily, avoids load-order issues) and

dependent:

has_many

Validation, scope, class method

ruby

module Spree
  module ProductDecorator
    def self.prepended(base)
      base.validates :external_id, uniqueness: { scope: :store_id }, allow_nil: true   # plus a DB index
      base.scope :recently_added, -> { where(created_at: 30.days.ago..) }
      base.scope :tagged_featured, -> { where("metadata->>'featured' = ?", 'true') }  # jsonb on PostgreSQL
      base.extend ClassMethods
    end

    module ClassMethods
      def search_by_name(query)
        where('LOWER(name) LIKE ?', "%#{sanitize_sql_like(query.downcase)}%")
      end
    end
  end

  Product.prepend(ProductDecorator)
end

Models with metadata have a single

metadata

JSON column (

public_metadata

private_metadata

no longer exist;

private_metadata

is a deprecated Ruby alias).

metadata

is internal, never exposed on the Store API — for storefront-visible or filterable data prefer a real column or a custom field. JSON operators (

->>

) are PostgreSQL syntax; MySQL/SQLite need different SQL.

Operation-level rules ("max 10 per order", "B2B customers only") are not model validations — they belong in a workflow

validate

hook so data migrations and staff corrections aren't blocked. Don't

clear_validators!

to relax a core rule; see

node_modules/@spree/docs/dist/developer/customization/validations.md

Override a method (call

super

)

ruby

module Spree
  module ProductDecorator
    def purchasable?
      return false if metadata[:embargoed]
      super
    end
  end

  Product.prepend(ProductDecorator)
end

Omitting

super

replaces the original entirely. Keep overrides to read-only/derived methods; anything that writes or moves money belongs in a workflow.

Cart & Order: methods live in

Spree::Purchase::*

concerns

Spree::Cart

(pre-checkout) and

Spree::Order

(placed, immutable) share behavior through concerns —

Spree::Purchase::Totals

::Addresses

::Taxation

::PaymentProcessing

::CheckoutSteps

(Cart only),

::Validations

, etc. (

spree_core

app/models/concerns/spree/purchase/

). Before decorating, find where the method is defined (

Spree::Cart.instance_method(:amount).owner

To change it for one side only, decorate
```
Spree::Cart
```
or
```
Spree::Order
```
(the prepended module sits in front of the concern,
```
super
```
reaches it).
For both, decorate both classes (or prepend to the concern itself:
```
Spree::Purchase::Totals.prepend(MyTotals)
```
— Ruby 3 propagates to classes that already included it).
Most cart/order logic you'd want to change (adding items, totals, completion) is in workflows, not models — use hooks.

Permit a new attribute on writes

ruby

Spree::Product.additional_permitted_attributes += [:brand_id]
Spree::LineItem.additional_permitted_attributes += [:gift_note]

Always
```
+=
```
(or
```
|=
```
). Never
```
<<
```
— the default is a frozen array (
```
FrozenError
```
) — and never
```
=
```
, which drops what other extensions added.
Put it in the model decorator's
```
prepended
```
(as above) or a
```
Rails.application.config.to_prepare
```
block, so it survives dev reloads of the engine's models.
API v3 controllers union this list with their own (
```
resource_permitted_attributes
```
);
```
Spree::PermittedAttributes
```
no longer exists.
Line items:
```
Spree::LineItem.additional_permitted_attributes
```
is the only thing that reaches the record through add-to-cart — sent top-level or inside
```
options
```
on
```
POST /carts/:id/items
```
(
```
Spree::Carts::AddItem
```
). Everything else in
```
options
```
is dropped, and
```
id
```
,
```
variant_id
```
and
```
quantity
```
can never be set that way (they were checked and priced already), even if you permit them.

Make it filterable

ruby

# config/initializers/spree.rb
Spree.ransack.add_attribute(Spree::Product, :brand_id)
Spree.ransack.add_association(Spree::Product, :brand)
Spree.ransack.add_scope(Spree::Product, :recently_added)

Without this,

q[brand_id_eq]=…

is silently dropped (200, unfiltered).

add_association

only widens the Admin API: the Store API follows just

storefront_ransackable_associations

(add

Spree::Product.storefront_ransackable_associations |= %w[brand]

in the same initializer if shoppers should filter by brand name) and the Seller API follows none. Hide a staff-only attribute from shoppers/sellers with

private_ransackable_attributes

(

{ store: [...], seller: [...] }

). See

spree-api-v3

Controller decorator patterns (API v3)

The only controllers Spree ships are the API ones —

Spree::Api::V3::Store::*

Spree::Api::V3::Admin::*

(and

::Seller::*

). There is no Rails admin or Rails storefront to decorate. Override the named hooks a

ResourceController

exposes —

scope

serializer_class

collection_includes

scope_includes

resource_permitted_attributes

model_class

— not actions.

Narrow what an endpoint returns

ruby

# server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb
module Spree::Api::V3::Admin
  module ProductsControllerDecorator
    protected

    # Chain onto super — it is already store-scoped (and ability-scoped on the
    # Admin API). Replacing it leaks other stores' records.
    # current_user is nil for secret-key (sk_) requests — guard with &.
    def scope
      return super if current_user&.spree_admin?

      super.where(discontinue_on: nil)
    end
  end
end

Spree::Api::V3::Admin::ProductsController.prepend(Spree::Api::V3::Admin::ProductsControllerDecorator)

On the Store API,

current_user

is the signed-in customer (nil for guests); on the Admin API it's the staff member (nil for secret-key requests). Hook methods are

protected

in the base — keep them

protected

in the decorator.

Swap the serializer for one endpoint

ruby

module Spree::Api::V3::Store
  module ProductsControllerDecorator
    protected

    def serializer_class
      MyStore::DetailedProductSerializer
    end
  end
end

Spree::Api::V3::Store::ProductsController.prepend(Spree::Api::V3::Store::ProductsControllerDecorator)

To swap it everywhere, use

Spree.api.product_serializer = …

instead (

spree-dependencies

A new action is a new controller

Don't add actions to Spree's controllers via decorators. Subclass the resource controller — you inherit pagination, Ransack filtering, prefixed IDs, error envelopes and authorization:

ruby

# server/app/controllers/spree/api/v3/admin/product_audits_controller.rb
module Spree::Api::V3::Admin
  class ProductAuditsController < ResourceController
    scoped_resource :products   # API-key scope: read_products / write_products (required on Admin controllers)

    protected

    def model_class = MyStore::ProductAudit
    def serializer_class = MyStore::ProductAuditSerializer
    def resource_permitted_attributes = [:note]
  end
end

ruby

# config/routes.rb
Spree::Core::Engine.add_routes do
  namespace :api, defaults: { format: 'json' } do
    namespace :v3 do
      namespace :admin do
        resources :product_audits
      end
    end
  end
end

spree generate api_resource

scaffolds model + serializer + controller + routes — see

spree-resource

API decorators must render JSON (

render_error

/ the standard error envelope), never flash/redirect.

Common pitfalls

Forgot
super
— silently replaces Spree's logic.

Instance variables in
prepended
(

@setting = true

) live on the module, not instances — use

base.class_attribute :setting, default: true

Constant references at boot —
```
has_many :variants
```
without
```
class_name: 'Spree::Variant'
```
can hit load-order errors.

File/module mismatch —

Spree::ProductDecorator

must live at

app/models/spree/product_decorator.rb

Decorating
Spree::Order
for checkout behavior — pre-checkout state is
```
Spree::Cart
```
; the order only exists after
```
Spree::Carts::Complete
```
.
belongs_to
without
optional: true
— "must exist" errors on existing rows.

Spree.user_class
— deprecated; decorate

Spree.customer_class

(default

Spree::Customer

) or

Spree.admin_user_class

(

Spree::AdminUser

Organizing many decorators

server/app/models/spree/
├── product_decorator.rb        # the only file that calls prepend
└── product/
    ├── brand_decorator.rb      # plain modules
    └── seo_decorator.rb

ruby

module Spree
  module ProductDecorator
    include Product::BrandDecorator
    include Product::SeoDecorator
  end

  Product.prepend(ProductDecorator)
end

Zeitwerk resolves the nested modules from their paths — no

require

require_dependency

(removed in Zeitwerk mode). Note the nested files also match the

*_decorator*.rb

glob, so they must not call

prepend

themselves.

Migrating callback decorators

A decorator adding

after_save :sync_to_erp

should become a subscriber:

ruby

# server/app/subscribers/product_sync_subscriber.rb   (spree generate subscriber ProductSync)
class ProductSyncSubscriber < Spree::Subscriber
  subscribes_to 'product.updated'

  def handle(event)
    ExternalSyncJob.perform_later(event.payload['id'])
  end
end

The payload is the serialized record (prefixed

id

), not a changeset. Registration and async behavior:

spree-events-webhooks

. Callbacks that touch money, stock or an external system inside an operation belong in a workflow hook instead.

Where to read further

node_modules/@spree/docs/dist/developer/customization/decorators.md

(https://spreecommerce.org/docs/developer/customization/decorators)

node_modules/@spree/docs/dist/developer/customization/validations.md

— hooks vs decorator validations vs registries

node_modules/@spree/docs/dist/developer/customization/api.md

— custom API endpoints

node_modules/@spree/docs/dist/developer/tutorial/model-and-api.md

— brand-on-product walkthrough

Related skills:

spree-workflows

spree-dependencies

spree-events-webhooks

spree-resource

spree-customization

spree-decorators

NPX Install

SKILL.md Content

Spree Decorators

Pick the right tool first

The pattern

Generators

Model decorator patterns

Add an association

Validation, scope, class method

Override a method (call
`super`
)

Cart & Order: methods live in
`Spree::Purchase::*`
concerns

Permit a new attribute on writes

Make it filterable

Controller decorator patterns (API v3)

Narrow what an endpoint returns

Swap the serializer for one endpoint

A new action is a new controller

Common pitfalls

Organizing many decorators

Migrating callback decorators

Where to read further

spree-decorators

NPX Install

SKILL.md Content

Spree Decorators

Pick the right tool first

The pattern

Generators

Model decorator patterns

Add an association

Validation, scope, class method

Override a method (call super)

Cart & Order: methods live in Spree::Purchase::* concerns

Permit a new attribute on writes

Make it filterable

Controller decorator patterns (API v3)

Narrow what an endpoint returns

Swap the serializer for one endpoint

A new action is a new controller

Common pitfalls

Organizing many decorators

Migrating callback decorators

Where to read further

Override a method (call
`super`
)

Cart & Order: methods live in
`Spree::Purchase::*`
concerns