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
---
title: Decorators
description: Use Spree decorators to add or modify behavior on core models, controllers, and helpers without forking the gem — patterns, file layout, and pitfalls.
---
<Warning>
**Decorators should be a last resort.** They tightly couple your code to Spree internals and can break during upgrades. Before using decorators, consider these modern alternatives that are safer and easier to maintain:
- **[Events & Subscribers](/developer/core-concepts/events)** - For reacting to model changes (after save, create, update, delete)
- **[Webhooks](/developer/core-concepts/webhooks)** - For notifying external services when events occur
- **[Dependencies](/developer/customization/dependencies)** - For swapping out services, serializers, and abilities
- **[Model extensions](#adding-to-a-model-without-a-decorator)** - For adding methods, associations, validations, and scopes to core models
- **[Dashboard Navigation](/developer/dashboard/customization/navigation)** - For adding menu items
- **[Dashboard Slots](/developer/dashboard/customization/slots)** - For adding your own UI to an existing dashboard screen
- **[Dashboard Tables](/developer/dashboard/customization/tables)** - For customizing list views
</Warning>
## When to Use Decorators vs Modern Alternatives
Before reaching for a decorator, check if your use case is better served by a modern alternative:
| Use Case | Instead of Decorator | Use This |
|----------|---------------------|----------|
| After-save hooks (sync to external service) | Model decorator with `after_save` | [Events subscriber](/developer/core-concepts/events) |
| Notify external service on changes | Model decorator with callbacks | [Webhooks](/developer/core-concepts/webhooks) |
| Custom add-to-cart logic | Service decorator | [Dependencies injection](/developer/customization/dependencies) |
| Custom API responses | Serializer decorator | [Dependencies injection](/developer/customization/dependencies) |
| Add a dashboard menu item | Controller decorator | [Navigation registry](/developer/dashboard/customization/navigation) |
| Add a section to a dashboard form | View decorator/override | [Slots](/developer/dashboard/customization/slots) |
| Narrow what an endpoint returns | Overriding an action | Controller decorator overriding `scope` |
| Accept a new attribute on write | Controller decorator | `Model.additional_permitted_attributes +=` |
| Add association to core model | Model decorator | [Model extensions](#adding-to-a-model-without-a-decorator) |
| Add validation or scope to core model | Model decorator | [Model extensions](#adding-to-a-model-without-a-decorator) |
| Add new method to core model | Model decorator | [Model extensions](#adding-to-a-model-without-a-decorator) |
| Make a new column [filterable](/developer/core-concepts/search-filtering) | - | Decorator (still appropriate) |
<Info>
Add associations, validations, scopes and new methods to core models with [model extensions](#adding-to-a-model-without-a-decorator). Use the other alternatives for **behavioral changes** like callbacks, hooks, and side effects. A decorator is left for **changing what an existing method does**, which nothing else covers.
</Info>
## Adding to a Model Without a Decorator
An extension writes an ordinary concern and registers it against the core model by name. Spree includes it in the model:
```ruby server/app/models/my_extension/product_warranty.rb
module MyExtension
module ProductWarranty
extend ActiveSupport::Concern
included do
has_one :warranty, class_name: 'MyExtension::Warranty', dependent: :destroy
scope :with_warranty, -> { joins(:warranty) }
end
def warranty_text
warranty&.summary
end
end
end
```
```ruby server/config/initializers/my_extension.rb
Rails.application.config.after_initialize do
Spree.model_extensions.add('Spree::Product', 'MyExtension::ProductWarranty')
end
```
- **It only adds.** A concern that would replace a method, a column's attribute or an association the model already has, or one another extension added, is refused at boot with an error naming both. A decorator would overwrite it without a word. To change what an existing method does, a decorator is still the tool.
- **The configured customer and admin user classes** are named `:customer` and `:admin_user`, since their class names vary: `Spree.model_extensions.add(:customer, 'MyExtension::CustomerWarranties')`.
- **It survives code reloading.** Spree includes the concerns again whenever development reloads the models.
- **`Spree.model_extensions.for('Spree::Product')`** lists what is registered for a model.
A method added this way can be shown in API responses with an [extension field](/developer/customization/api#adding-a-field-from-an-extension).
## Overview
Spree's models, API controllers and helpers can be extended or overridden to meet your requirements using standard Ruby idioms.
The convention is a file under `server/app/models/spree` or `server/app/controllers/spree`, named after the original class with `_decorator` appended. The generators below place it for you.
<Note>
There is nothing else to decorate. The dashboard is a React application that
talks to the Admin API, and the storefront is your own — so the only
controllers Spree ships are the API ones, and the only views are the emails.
Customize the dashboard through
[its own extension points](/developer/dashboard/customization/quickstart).
</Note>
## Why Use Decorators?
When working with Spree, you'll often need to add functionality to existing models like `Spree::Product` or `Spree::Order`. However, you shouldn't modify these files directly because:
1. **Upgrades** - Your changes would be lost when updating Spree
2. **Maintainability** - It's hard to track what you've customized
3. **Conflicts** - Direct modifications can conflict with Spree's code
Instead, we use **decorators** - a Ruby pattern that lets you add or modify behavior of existing classes without changing their original source code.
## How Decorators Work
In Ruby, classes are "open" - you can add methods to them at any time. Decorators leverage this by:
1. Creating a module with your new methods
2. Using `Module#prepend` to inject your module into the class's inheritance chain
3. Your methods run first, and can call `super` to invoke the original method
```ruby
# This is the basic pattern
module Spree
module ProductDecorator
# Add a new method
def my_new_method
"Hello from decorator!"
end
# Override an existing method
def existing_method
# Do something before
result = super # Call the original method
# Do something after
result
end
end
Product.prepend(ProductDecorator)
end
```
The key line is `Product.prepend(ProductDecorator)` - this inserts your module at the beginning of the method lookup chain, so your methods are found first.
## Generating Decorators
Spree provides generators to create decorator files with the correct structure:
### Model Decorator Generator
<CodeGroup>
```bash Spree CLI (Docker)
spree generate model_decorator Spree::Product
```
```bash Without Spree CLI
bin/rails g spree:model_decorator Spree::Product
```
</CodeGroup>
This creates `server/app/models/spree/product_decorator.rb`:
```ruby
module Spree
module ProductDecorator
def self.prepended(base)
# Class-level configurations go here
end
end
Product.prepend(ProductDecorator)
end
```
### Controller Decorator Generator
<CodeGroup>
```bash Spree CLI (Docker)
spree generate controller_decorator Spree::Api::V3::Admin::ProductsController
```
```bash Without Spree CLI
bin/rails g spree:controller_decorator Spree::Api::V3::Admin::ProductsController
```
</CodeGroup>
This creates `server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb`:
```ruby
module Spree::Api::V3::Admin
module ProductsControllerDecorator
def self.prepended(base)
# base.before_action :my_filter
end
# add custom methods here
end
end
Spree::Api::V3::Admin::ProductsController.prepend Spree::Api::V3::Admin::ProductsControllerDecorator
```
The generator accepts any namespace depth. `Spree::ProductsController` produces a top-level `module Spree` wrapper; `Spree::Api::V3::Store::ProductsController` produces a `module Spree::Api::V3::Store` wrapper. The final `.prepend` line is always fully qualified.
## Decorating Models
### Changing Behavior of Existing Methods
The most common use case is changing the behavior of existing methods. When overriding a method, you can call `super` to invoke the original implementation:
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def available?
# Add custom logic before
return false if discontinued?
# Call the original method
super
end
end
Product.prepend(ProductDecorator)
end
```
<Warning>
Always consider whether you need to call `super` when overriding methods. Omitting it completely replaces the original behavior, which may break functionality.
</Warning>
### Adding New Methods
Add new instance methods directly in the decorator module:
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def featured?
metadata[:featured] == true
end
def days_until_available
return 0 if available_on.nil? || available_on <= Time.current
(available_on.to_date - Date.current).to_i
end
end
Product.prepend(ProductDecorator)
end
```
### Adding Associations
Use the `self.prepended(base)` callback to add associations:
```ruby server/app/models/spree/product_decorator.rb
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
end
end
Product.prepend(ProductDecorator)
end
```
### Adding Validations
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def self.prepended(base)
base.validates :external_id, presence: true, uniqueness: true
base.validates :weight, numericality: { greater_than: 0 }, allow_nil: true
end
end
Product.prepend(ProductDecorator)
end
```
### Adding Scopes
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def self.prepended(base)
base.scope :featured, -> { where("metadata->>'featured' = ?", 'true') }
base.scope :recently_added, -> { where('created_at > ?', 30.days.ago) }
base.scope :on_sale, -> { joins(:variants).where('spree_prices.compare_at_amount > spree_prices.amount') }
end
end
Product.prepend(ProductDecorator)
end
```
### Adding Class Methods
Use `extend` within the `prepended` callback to add class methods:
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def self.prepended(base)
base.extend ClassMethods
end
module ClassMethods
def search_by_name(query)
where('LOWER(name) LIKE ?', "%#{query.downcase}%")
end
end
end
Product.prepend(ProductDecorator)
end
```
Usage:
```ruby
Spree::Product.search_by_name('shirt')
```
## Decorating Controllers
The only controllers Spree ships are the API ones, under
`Spree::Api::V3::Store` and `Spree::Api::V3::Admin`. There is no server-rendered
storefront or admin to decorate — the dashboard is a React app that talks to the
Admin API, and the storefront is yours.
<Warning>
**Reach for a decorator last.** A `ResourceController` subclass exposes named
hooks — `scope`, `permitted_params`, `serializer_class`, `collection_includes`
— and overriding one of those in a decorator is safe. Overriding an *action*
couples your code to Spree's internals and is what breaks on upgrade.
</Warning>
### Narrowing what an endpoint returns
The most common reason to decorate: restrict a listing beyond what the store
scope already does.
```bash
spree generate controller_decorator Spree::Api::V3::Admin::ProductsController
```
```ruby server/app/controllers/spree/api/v3/admin/products_controller_decorator.rb
module Spree::Api::V3::Admin
module ProductsControllerDecorator
protected
# `super` is already scoped to the current store. Chain onto it — never
# replace it, or the endpoint stops being scoped and starts returning
# another store's records. `current_user` is nil for a secret-key
# request, hence `&.` — a caller that is not a staff member gets the
# narrowed scope.
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
)
```
`current_user` is the signed-in staff member, and `spree_admin?` asks whether
they hold the admin role for the current store.
<Warning>
`current_user` is only set when the request carries a staff token. A request
authenticated with a [secret API key](/api-reference/admin-api/authentication)
has no user, so `current_user` is `nil` — guard for it, or a server-to-server
integration hits `NoMethodError` on every call.
</Warning>
### Accepting an extra attribute
If your decorator added a column to a core model, the controller has to permit
it — but you rarely need a decorator for that. Extensions append to the model's
own list from an initializer:
```ruby server/config/initializers/spree.rb
Spree::Product.additional_permitted_attributes += [:brand_id]
```
Always `+=`, never `=`, or you drop what another extension added.
### A new endpoint is a new controller
To add an action, write your own controller rather than decorating one of
Spree's. It inherits the same pagination, filtering and authorization:
```ruby server/app/controllers/spree/api/v3/admin/product_audits_controller.rb
module Spree::Api::V3::Admin
class ProductAuditsController < ResourceController
# Names the API-key scope this endpoint needs: `read_products` for
# index/show, `write_products` for everything else. Every Admin API
# controller must declare one.
scoped_resource :products
protected
def model_class
Spree::ProductAudit
end
def serializer_class
MyApp::ProductAuditSerializer
end
end
end
```
Add the route to your application's `config/routes.rb`, inside the engine's
route hook. See [extending the API](/developer/customization/api).
<Info>
**For side effects, use events rather than a decorator.** Subscribing to
`product.created` runs your code for every caller — the dashboard, a secret
API key, an import, the console. A controller override only fires for
requests that happen to pass through that controller. See
[Events](/developer/core-concepts/events).
</Info>
## Best Practices
<CardGroup cols={2}>
<Card title="Use the prepended callback" icon="code">
Always use `self.prepended(base)` for class-level additions like associations, validations, scopes, and callbacks.
</Card>
<Card title="Keep decorators focused" icon="crosshairs">
Each decorator should have a single responsibility. Create multiple decorators for different concerns if needed.
</Card>
<Card title="Call super when overriding" icon="arrow-up">
When overriding methods, call `super` to preserve original behavior unless you intentionally want to replace it entirely.
</Card>
<Card title="Test decorated behavior" icon="flask-vial">
Write tests specifically for your decorated functionality to catch regressions during upgrades.
</Card>
</CardGroup>
### Organizing Multiple Decorators
If you have many customizations for a single class, consider splitting them into focused decorators:
```
server/app/models/spree/
├── product_decorator.rb # Main decorator (loads others)
├── product/
│ ├── brand_decorator.rb # Brand association
│ ├── inventory_decorator.rb # Inventory customizations
│ └── seo_decorator.rb # SEO-related methods
```
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
include Product::BrandDecorator
include Product::InventoryDecorator
include Product::SeoDecorator
end
Product.prepend(ProductDecorator)
end
```
Each focused module is a plain module — only the top-level decorator calls
`prepend`. Autoloading resolves them from their paths, so nothing needs
requiring by hand.
## Common Pitfalls
### Forgetting to Call Super
```ruby
# ❌ Bad - completely replaces original behavior
def available?
in_stock? && active?
end
# ✅ Good - extends original behavior
def available?
super && custom_availability_check
end
```
### Using Instance Variables in prepended
```ruby
# ❌ Bad - instance variables don't work in prepended
def self.prepended(base)
@custom_setting = true # This won't work as expected
end
# ✅ Good - use class attributes or methods
def self.prepended(base)
base.class_attribute :custom_setting, default: true
end
```
### Circular Dependencies
Be careful when decorators depend on each other:
```ruby
# ❌ Bad - can cause loading issues
# product_decorator.rb
def self.prepended(base)
base.has_many :variants # Variant decorator might not be loaded yet
end
# ✅ Good - use strings for class names
def self.prepended(base)
base.has_many :variants, class_name: 'Spree::Variant'
end
```
## Migrating from Decorators to Modern Patterns
If you have existing decorators that use callbacks for side effects, consider migrating them to Events subscribers for better maintainability.
### Example: Migrating an After-Save Callback
**Before (Decorator with callback):**
```ruby server/app/models/spree/product_decorator.rb
module Spree
module ProductDecorator
def self.prepended(base)
base.after_save :sync_to_external_service
end
private
def sync_to_external_service
ExternalSyncJob.perform_later(self) if saved_change_to_name?
end
end
Product.prepend(ProductDecorator)
end
```
**After (Events subscriber):**
```ruby server/app/subscribers/product_sync_subscriber.rb
class ProductSyncSubscriber < Spree::Subscriber
subscribes_to 'product.updated'
def handle(event)
product = Spree::Product.find_by_prefix_id(event.payload['id'])
return unless product
ExternalSyncJob.perform_later(product)
end
end
```
The payload is the record as the API serializes it, so it carries the new
values rather than a list of what changed. When a subscriber only cares about
one attribute, compare against what you last synced rather than looking for a
changeset in the event.
### Benefits of Migration
<CardGroup cols={2}>
<Card title="Loose coupling" icon="link-slash">
Your code doesn't depend on Spree internals. Events provide a stable interface.
</Card>
<Card title="Easier upgrades" icon="arrow-up">
Events-based code is less likely to break when Spree is updated.
</Card>
<Card title="Better testability" icon="flask-vial">
Subscribers can be tested in isolation without loading the full model.
</Card>
<Card title="Async by default" icon="bolt">
Subscribers run via ActiveJob, keeping your requests fast.
</Card>
</CardGroup>
## Related Documentation
- [Events](/developer/core-concepts/events) - Learn about Spree's event system
- [Webhooks](/developer/core-concepts/webhooks) - HTTP callbacks for external integrations
- [Dependencies](/developer/customization/dependencies) - Swap core services with your own
- [Extending the API](/developer/customization/api) - Add your own endpoints
- [Dashboard customization](/developer/dashboard/customization/quickstart) - Extend the dashboard from its own React app
- [Extending Core Models Tutorial](/developer/tutorial/model-and-api) - Step-by-step guide to connecting custom models with Spree core
- [Customization Overview](/developer/customization/quickstart) - General customization patterns