Spree Customization Quickstart

What you want to do	Recommended approach
Change store settings (currency, markets, languages)	Store settings
Tweak Spree behavior globally	Configuration
Run your own logic inside checkout, cancellation, refunds	Workflow hooks
Block an operation from happening	Workflow hooks — `validate`
React after something happened (sync, notifications)	Events & subscribers
Add or reorder checkout steps	Checkout registry
Swap tax, delivery rate, search or fulfillment behavior	Providers
Add searchable/filterable fields	Search & filtering
Use your own user model or identity provider	Authentication
Notify external services	Webhooks
Replace a whole workflow or service	Dependencies
Add associations/validations to models	Decorators (last resort)

Store settings

Best for: currency, markets, delivery zones, languages, and other business settings.Most day-to-day configuration is data, not code. Change it in the dashboard under Settings — no deploy required.

Configuration

Best for: tweaking Spree’s behavior globally.

config/initializers/spree.rb

Spree.config do |config|
  config.minimum_password_length = 10
end

See Configuration.

Workflow hooks

Best for: running your own logic inside a core flow — checkout completion, order cancellation, refunds, fulfillment creation.

Hooks are the headline extension point in Spree, so you don’t have to replace an entire class and keep your copy in sync with core forever.

config/initializers/spree.rb

Spree.hooks.register('carts.complete.validate') do |flow|
  flow.reject!('We cannot deliver to this region') unless deliverable?(flow.cart)
end

Pass a class instead of a block for anything longer than a line:

Spree.hooks.register('carts.complete.after_finalize', 'MyApp::PushOrderToERP')

There are three families of hook:

Family	Naming	What it can do
validate	`validate`	Veto the operation with `flow.reject!(message)`
lifecycle	past tense — `after_finalize`, `after_cancel`	React to what happened; read-only
context	`set_*_context`, `get_provider_data`	Return a hash that gets merged into the flow’s data

Hook keys are validated after boot, so a typo fails startup rather than silently never running.See Services & Workflows for the full list of flows and their hooks.

Events and subscribers

Best for: reacting after something happened — syncing to external systems, notifications, audit logging.

app/subscribers/spree/order_placed_subscriber.rb

module Spree
  class OrderPlacedSubscriber < Spree::Subscriber
    subscribes_to 'order.placed'

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

      MyApp::ERP.push(order)
    end
  end
end

Events or hooks? A hook runs inside the flow and can influence or block it. An event fires after the fact and cannot. Reach for an event unless you need to change the outcome.See Events.

Checkout steps

Best for: adding, removing or reordering checkout steps.Spree has no checkout state machine. A cart reports what it still needs, and you can add to that list:

config/initializers/spree.rb

Spree::Checkout::Registry.register_step(
  name: :loyalty,
  before: :payment,
  satisfied: ->(cart) { cart.metadata['loyalty_number'].present? },
  requirements: ->(cart) {
    [{ step: 'loyalty', field: 'loyalty_number', message: 'Loyalty number is required' }]
  }
)

Or attach a requirement to an existing step:

Spree::Checkout::Registry.add_requirement(
  step: :payment,
  field: :po_number,
  message: 'PO number is required',
  satisfied: ->(cart) { cart.metadata['po_number'].present? }
)

Registered requirements appear in the Cart API’s requirements array, so your storefront renders them without duplicating any rules.See Carts.

Providers

Best for: swapping a whole area of behavior for your own implementation.Spree exposes pluggable providers for the domains that vary most between businesses:

Provider	Controls
Tax provider	How tax is calculated, per market
Delivery rate provider	How delivery is priced — flat rates or live carrier rates
Fulfillment provider	How a delivery type behaves — shipping, digital, pickup
Search provider	Database or Meilisearch
Payout provider	Where marketplace payouts go

Each is a class you register and select on the relevant record, so no conditional code lands in core.See Fulfillments and Taxes.

Search and filtering

Best for: making custom fields searchable and sortable in the dashboard and API.

config/initializers/spree.rb

Spree.ransack.add_attribute(Spree::Product, :erp_id)
Spree.ransack.add_association(Spree::Product, :brand)
Spree.ransack.add_scope(Spree::Product, :featured)

See Search & Filtering.

Authentication

Best for: using your own user model or identity provider.Spree owns its authentication stack rather than depending on Devise, and separates the customer identity from the staff identity. Point Spree at your own classes with Spree.customer_class and Spree.admin_user_class.See Authentication.

Webhooks

Best for: notifying external services — ERPs, CRMs, fulfillment systems — without writing Ruby.Configure them in the dashboard under Settings → Webhooks, or through the Admin API.See Webhooks.

Dependencies

Best for: replacing an entire workflow or service with your own class.

config/initializers/spree.rb

Spree::Dependencies.cart_add_item_workflow = 'MyApp::Carts::AddItem'

Seam names end in _workflow. The old *_service names still resolve with a warning, but writes to them are ignored — a class written against the old service contract isn’t interchangeable with a workflow. Update the key if your code still uses the old name.

Prefer a hook when you only need to add behavior. Replace the class only when you need to change what the flow fundamentally does.See Dependencies.

Decorators

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

Decorators couple your code to Spree internals and are the most common cause of painful upgrades.Do not use decorators for:

Logic inside a core flow → use workflow hooks
After-save callbacks → use events
External service sync → use webhooks
Replacing a service → use dependencies
Admin UI changes → use dashboard customization

They remain appropriate for structural additions:

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.scope :featured, -> { where(featured: true) }
    end

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

  Product.prepend(ProductDecorator)
end

See Decorators.

Develop

Quickstart

Quick reference

Choosing between hooks, events and dependencies

​Quick reference

​Choosing between hooks, events and dependencies

​Related

Quick reference

Choosing between hooks, events and dependencies

Related