Spree Customization Quickstart

What you want to do	Recommended approach
Change store settings (currency, zones, languages)	Store Settings
Tweak Spree behavior globally	Configuration
React to model changes (sync, notifications)	Events & Subscribers
Notify external services	Webhooks
Swap core services (cart, checkout, etc.)	Dependencies
Add admin menu items	Admin Navigation
Add sections to admin forms	Admin Partials
Add searchable/filterable fields	Ransack Configuration
Add associations/validations to models	Decorators (last resort)

Store settings

Best for: Changing currency, shipping zones, languages, and other business settings.There’s a lot of Store settings you can change in the admin panel without touching the code.Go to Admin > Settings

Configuration

Best for: Tweaking Spree’s behavior globally without modifying source code.Global application configuration allows you to customize various aspects of Spree:

config/initializers/spree.rb

Spree.config do |config|
  config.allow_guest_checkout = false
  config.products_per_page = 20
end

Please see Configuration section for more information.

Events and Subscribers

Best for: Reacting to model changes, syncing with external services, sending notifications, audit logging.

Events are the recommended way to add behavior when something happens in Spree, replacing the need for decorator callbacks.

Spree’s event system lets you subscribe to events like order.completed, product.updated, payment.paid, etc.:

app/subscribers/order_completed_subscriber.rb

class OrderCompletedSubscriber < Spree::Subscriber
  subscribes_to 'order.completed'

  def handle(event)
    order = Spree::Order.find_by_prefix_id(event.payload['id'])
    return unless order

    # Sync to external service, send notification, etc.
    ExternalService.notify_order_placed(order)
  end
end

Key benefits:

Loose coupling - your code doesn’t depend on Spree internals
Async by default - keeps requests fast
Easier testing and upgrades

Please see Events section for more information.

Webhooks

Best for: Notifying external services (ERPs, CRMs, fulfillment systems) when events occur.Webhooks send HTTP POST requests to external URLs when Spree events happen:

Order completed → Notify fulfillment system
Product updated → Sync with PIM
Customer created → Add to CRM

Configure webhooks in Admin > Developers > Webhooks or via the API.Please see Webhooks section for more information.

Dependencies

Best for: Swapping core services, serializers, and abilities with your own implementations.Spree allows you to replace core classes without modifying them:

config/initializers/spree.rb

Spree::Dependencies.cart_add_item_service = "MyCartAddItemService"
Spree::Dependencies.cart_remove_item_service = "MyCartRemoveItemService"

This is cleaner than decorating services because you provide a complete replacement rather than patching behavior.Please see Dependencies section for more information.

Admin Extensions

Best for: Adding menu items, form sections, dashboard widgets, and other UI elements to the admin panel.Spree provides declarative APIs for extending the admin without decorators or view overrides:Navigation API - Add menu items:

config/initializers/spree.rb

Rails.application.config.after_initialize do
  Spree.admin.navigation.sidebar.add :brands,
    label: :brands,
    url: :admin_brands_path,
    icon: 'award',
    position: 35
end

Partials API - Add sections to forms:

config/initializers/spree.rb

Spree.admin.partials.product_form << 'spree/admin/products/erp_section'

Please see:

Admin Navigation - For adding menu items
Admin Partials - For extending UI
Admin Tables - For customizing list views

Search and Filtering

Best for: Making custom fields searchable/sortable in the admin and API.Instead of decorating models to add ransackable_attributes, use the Ransack configuration API:

config/initializers/spree.rb

Spree.ransack.add_attribute :product, :erp_id
Spree.ransack.add_association :product, :brand

Please see Search & Filtering section for more information.

Authentication

Best for: Using your own user model or authentication system.Spree allows you to use your own authentication system instead of the default Devise-based one.You can find more information in the Authentication section.

Checkout flow

Best for: Customizing checkout steps and flow.With Spree you can change the checkout flow to fit your business needs - add steps, remove steps, or change the order.Please see Checkout flow customization section for more information.

Decorators

Best for: Adding associations, validations, scopes, and methods to Spree models. Use as a last resort.

Decorators should be used only when no other option works. They tightly couple your code to Spree internals and can break during upgrades.Do NOT use decorators for:

After-save callbacks → Use Events instead
External service sync → Use Webhooks instead
Custom service logic → Use Dependencies instead
Admin UI changes → Use Admin Extensions instead

Decorators are still appropriate for structural changes:

app/models/spree/product_decorator.rb

module Spree
  module ProductDecorator
    def self.prepended(base)
      base.belongs_to :brand, class_name: 'MyApp::Brand', optional: true
      base.validates :external_id, presence: true
      base.scope :featured, -> { where(featured: true) }
    end

    def full_title
      "#{brand&.name} #{name}"
    end
  end

  Product.prepend(ProductDecorator)
end

Please see Decorators section for more information.

Tutorial

Admin Panel

Customization Reference

Quickstart

Quick Reference

​Quick Reference

Quick Reference