Extending Core Models

This is a backend customization. You need to perform it in the backend directory if you used create-spree-app to set up your Spree application.

In this tutorial, we’ll connect our custom Brand model with Spree’s core Product model. This is a common pattern when building features that need to integrate with existing Spree functionality.

This guide assumes you’ve completed the Model and Admin tutorials.

What We’re Building

By the end of this tutorial, you’ll have:

Products associated with Brands
A brand selector in the Product admin form
Understanding of how to safely extend Spree core models

Choosing the Right Approach

Before extending Spree models, consider which approach fits your needs best:

What you need	Recommended approach
Add association (belongs_to, has_many)	Decorator (this tutorial)
Add validation or scope	Decorator
Add new instance/class method	Decorator
React to model changes (after save, etc.)	Events subscriber
Sync with external service on changes	Events or Webhooks
Add searchable/filterable field	Ransack configuration
Add admin UI elements	Admin Partials

This tutorial uses decorators because we’re adding a structural association between models. For behavioral changes like callbacks, prefer Events instead - they’re easier to test and maintain.

Understanding 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:

Upgrades - Your changes would be lost when updating Spree
Maintainability - It’s hard to track what you’ve customized
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:

Creating a module with your new methods
Using Module#prepend to inject your module into the class’s inheritance chain
Your methods run first, and can call super to invoke the original method

# 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.

Step 1: Create the Migration

First, add a brand_id column to the products table:

spree generate migration AddBrandIdToSpreeProducts brand_id:integer:index

bin/rails g migration AddBrandIdToSpreeProducts brand_id:integer:index

Edit the migration to add an index (but no foreign key constraint, keeping it optional):

db/migrate/XXXXXXXXXXXXXX_add_brand_id_to_spree_products.rb

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

Run the migration:

spree migrate

bin/rails db:migrate

We intentionally don’t add a foreign key constraint. This keeps the association optional and avoids issues if brands are deleted. Spree follows this pattern for flexibility.

Step 2: Generate the Product Decorator

Spree provides a generator to create decorator files with the correct structure:

spree generate model_decorator Spree::Product

bin/rails g spree:model_decorator Spree::Product

This creates app/models/spree/product_decorator.rb:

app/models/spree/product_decorator.rb

module Spree
  module ProductDecorator
    def self.prepended(base)
      # Class-level configurations go here
    end
  end

  Product.prepend(ProductDecorator)
end

Step 3: Add the Brand Association to Product

Update the decorator to add the belongs_to association:

app/models/spree/product_decorator.rb

module Spree
  module ProductDecorator
    def self.prepended(base)
      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
    end
  end

  Product.prepend(ProductDecorator)
end

Understanding the Code

self.prepended(base) - This callback runs when the module is prepended to a class. The base parameter is the class being decorated (Spree::Product)
base.belongs_to - We call class methods on base to add associations, validations, scopes, etc.
optional: true - Products don’t require a brand (the brand_id can be NULL)

Step 4: Add Products Association to Brand

Now update your Brand model to define the reverse association:

app/models/spree/brand.rb

module Spree
  class Brand < Spree::Base
    # ... existing code ...

    has_many :products, class_name: 'Spree::Product', dependent: :nullify

    # ... rest of your model ...
  end
end

We use dependent: :nullify instead of dependent: :destroy. When a brand is deleted, products will have their brand_id set to NULL rather than being deleted. This is safer for e-commerce data.

Step 5: Permit the Brand Parameter

For the admin form to save the brand association, we need to permit the brand_id parameter. Add to your Spree initializer:

config/initializers/spree.rb

# .. other code ..

Spree::PermittedAttributes.product_attributes << :brand_id

Step 6: Add Brand Selector to Product Admin Form

Create a partial to inject the brand selector into the product form. Spree’s admin product form has injection points for customization. Create the partial:

app/views/spree/admin/products/_brand_field.html.erb

<div class="card mb-6">
  <div class="card-header">
    <h5 class="card-title"><%= Spree.t(:brand) %></h5>
  </div>
  <div class="card-body">
  <%= f.spree_select :brand_id,
      Spree::Brand.order(:name).pluck(:name, :id),
      { include_blank: true, label: Spree.t(:brand) } %>
</div>

Spree 5.2+
Spree 5.1 and below

config/initializers/spree.rb

Rails.application.config.after_initialize do
  Spree.admin.partials.product_form_sidebar << 'spree/admin/products/brand_field'
end

config/initializers/spree.rb

Rails.application.config.spree_admin.product_form_sidebar_partials << 'spree/admin/products/brand_field'

Step 7: Add Translation

Add the translation for the brand label:

config/locales/en.yml

en:
  spree:
    brand: Brand

Testing the Association

Verify everything works in the Rails console:

# Create a brand and product
brand = Spree::Brand.create!(name: 'Nike')
product = Spree::Product.first
product.update!(brand: brand)

# Test associations
product.brand        # => #<Spree::Brand id: 1, name: "Nike"...>
brand.products       # => [#<Spree::Product...>]
brand.products.count # => 1

Decorator Best Practices

Use prepended callback

Always use self.prepended(base) for class-level additions like associations, validations, and scopes.

Keep decorators focused

Each decorator should have a single responsibility. Create multiple decorators if needed.

Call super when overriding

When overriding methods, call super to preserve original behavior unless you intentionally want to replace it.

Test decorated behavior

Write tests specifically for your decorated functionality to catch regressions.

Common Decorator Patterns

Adding Validations

def self.prepended(base)
  base.validates :custom_field, presence: true
end

Adding Scopes

def self.prepended(base)
  base.scope :featured, -> { where(featured: true) }
end

Adding Callbacks

For callbacks that trigger side effects (syncing to external services, sending notifications, etc.), use Events subscribers instead of decorator callbacks. Events are easier to test and won’t break during Spree upgrades.

Decorator approach (use only for simple, internal logic):

def self.prepended(base)
  base.before_save :normalize_name
end

def normalize_name
  self.name = name.strip.titleize if name.present?
end

Events approach (recommended for side effects): subscribe to product.updated and react in a Spree::Subscriber — no decorator, no callback coupling. The Events & Webhooks tutorial builds this out fully, including external-system sync (OMS, warehouse) and outbound webhooks.

Adding Class Methods

def self.prepended(base)
  base.extend ClassMethods
end

module ClassMethods
  def my_class_method
    # Class method logic
  end
end

Complete Files

Product Decorator

app/models/spree/product_decorator.rb

module Spree
  module ProductDecorator
    def self.prepended(base)
      base.belongs_to :brand, class_name: 'Spree::Brand', optional: true
    end
  end

  Product.prepend(ProductDecorator)
end

Brand Model (Updated)

app/models/spree/brand.rb

module Spree
  class Brand < Spree::Base
    has_many :products, class_name: 'Spree::Product', dependent: :nullify

    has_one_attached :logo
    has_rich_text :description

    validates :name, presence: true
  end
end

SEO features like slugs, meta titles, and FriendlyId are covered in the Slugs documentation.

Spree Initializer Additions

config/initializers/spree.rb

# Permit brand_id in product params
Spree::PermittedAttributes.product_attributes << :brand_id

Spree 5.2+
Spree 5.1 and below

config/initializers/spree.rb

Rails.application.config.after_initialize do
  # Add brand field to product form
  Spree.admin.partials.product_form << 'spree/admin/products/brand_field'
end

config/initializers/spree.rb

# Add brand field to product form
Rails.application.config.spree_admin.product_form_partials << 'spree/admin/products/brand_field'

Next Step

Now that Brands are connected to Products, let’s expose them through the Store API:

6. API

Create API endpoints for brands and extend the Product API response

Model Tutorial - Creating the Brand model
Admin Tutorial - Building the admin interface
API Tutorial - Exposing brands through the API
Events & Webhooks tutorial - Subscribers, custom events, and webhooks in the Brand storyline
Events - Subscribe to model changes without decorators
Webhooks - HTTP callbacks for external integrations
Decorators - Full decorator reference
Customization Overview - More customization patterns
Products - Product model documentation

Tutorial

Admin Panel

Customization Reference

What We’re Building

Choosing the Right Approach

Understanding Decorators

How Decorators Work

Step 1: Create the Migration

Step 2: Generate the Product Decorator

Step 3: Add the Brand Association to Product

Understanding the Code

Step 4: Add Products Association to Brand

Step 5: Permit the Brand Parameter

Step 6: Add Brand Selector to Product Admin Form

Step 7: Add Translation

Testing the Association

Decorator Best Practices

Use prepended callback

Keep decorators focused

Call super when overriding

Test decorated behavior

Common Decorator Patterns

Adding Validations

Adding Scopes

Adding Callbacks

Adding Class Methods

Complete Files

Product Decorator

Brand Model (Updated)

Spree Initializer Additions

Next Step

6. API

​What We’re Building

​Choosing the Right Approach

​Understanding Decorators

​How Decorators Work

​Step 1: Create the Migration

​Step 2: Generate the Product Decorator

​Step 3: Add the Brand Association to Product

​Understanding the Code

​Step 4: Add Products Association to Brand

​Step 5: Permit the Brand Parameter

​Step 6: Add Brand Selector to Product Admin Form

​Step 7: Add Translation

​Testing the Association

​Decorator Best Practices

Use prepended callback

Keep decorators focused

Call super when overriding

Test decorated behavior

​Common Decorator Patterns

​Adding Validations

​Adding Scopes

​Adding Callbacks

​Adding Class Methods

​Complete Files

​Product Decorator

​Brand Model (Updated)

​Spree Initializer Additions

​Next Step

6. API

​Related Documentation

What We’re Building

Choosing the Right Approach

Understanding Decorators

How Decorators Work

Step 1: Create the Migration

Step 2: Generate the Product Decorator

Step 3: Add the Brand Association to Product

Understanding the Code

Step 4: Add Products Association to Brand

Step 5: Permit the Brand Parameter

Step 6: Add Brand Selector to Product Admin Form

Step 7: Add Translation

Testing the Association

Decorator Best Practices

Common Decorator Patterns

Adding Validations

Adding Scopes

Adding Callbacks

Adding Class Methods

Complete Files

Product Decorator

Brand Model (Updated)

Spree Initializer Additions

Next Step

Related Documentation