Services & Workflows

Overview

Spree’s business logic lives in two kinds of plain Ruby classes. Both are called the same way and both return the same result object, so as a caller you never need to know which one you’re using. Services (app/services/) are the default. A service is an ordinary class with a call method — creating a customer, updating a price, removing an item from a cart. Most of Spree is services. Workflows (app/workflows/) handle the flows that need more: completing a checkout, cancelling an order, capturing a payment, creating a fulfillment. These are the operations where something can go wrong halfway through, where money moves, or where you might want to inject your own logic partway. A workflow earns its place by needing at least one of:

Extension points — named places where your code can run inside the flow
External calls — payment gateways, carrier APIs, anything over the network
Compensation — undoing earlier work when a later step fails

Everything else stays a service. If you’re writing a plain create-update-delete operation, write a service.

Calling them

Identical for both:

result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 2)

if result.success?
  line_item = result.value
else
  puts result.error.to_s
end

Never raise on expected failures — check result.success?. See Dependencies for how to swap either one for your own class.

Extending a workflow with hooks

Before hooks, customizing a flow meant replacing the whole class and keeping your copy in sync with every Spree release. Hooks let you run your own code at a named point inside a flow you don’t own. Register in config/initializers/spree.rb:

Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')

The key is <workflow>.<hook>. Handlers are stored as class name strings, resolved when the hook fires — that keeps registration safe at boot time and survives code reloading in development. A block works for one-liners:

Spree.hooks.register('orders.cancel.after_cancel') do |workflow|
  MyStore::Analytics.track(:order_cancelled, workflow.order.number)
end

Your handler is a class with a call method that receives the workflow:

module MyStore
  class CheckPurchaseLimit
    def call(workflow)
      # every #perform keyword is a reader: cart, variant, quantity, ...
      return if workflow.quantity <= 10

      workflow.errors.add(:quantity, :purchase_limit_exceeded,
                          message: 'You can order at most 10 of this item.')
      workflow.reject!
    end
  end
end

workflow.errors is an ActiveModel::Errors, the same object a model uses. A rejection therefore reaches the API in the shape clients already handle for validation failures — the field name, a symbolic code, and the message:

{
  "error": {
    "code": "validation_error",
    "message": "Quantity You can order at most 10 of this item.",
    "details": { "quantity": ["You can order at most 10 of this item."] }
  }
}

Add to :base for a rejection that isn’t about one field. reject!('message') with an argument is shorthand for exactly that.

Hook keys are validated at boot. Registering against a hook that doesn’t exist raises Spree::Hooks::UnknownHookError with the list of valid hooks for that workflow, so a typo fails immediately instead of silently never firing.

Every hook can have many handlers

A hook is not a single slot. Your extension, another extension and the host application can all register against the same key, and every one of them runs. Assume you are never alone on a hook.

Spree.hooks.register('carts.add_item.validate', 'MyStore::CheckPurchaseLimit')
Spree.hooks.register('carts.add_item.validate', 'OtherGem::CheckChannelRules')
Spree.hooks.register('carts.add_item.validate') { |workflow| ... }
# all three run

Handlers run in registration order — the order the register calls happened, which for gems is initializer load order. Don’t depend on it. If your handler only makes sense after another one has run, you have a sequencing requirement that hooks don’t express; put both pieces in one handler. Registering the same class twice is a no-op. register deduplicates by class name, so an initializer that runs twice (or a gem registering defensively) won’t double up. Two different classes are two handlers, and two separate blocks are always two handlers — blocks can’t be compared, so prefer class names anywhere registration might repeat. What “many handlers” means differs by kind:

Kind	With several handlers
`validate`	Runs in order until one rejects. The first `reject!` stops the flow — later validate handlers never run, so don’t rely on yours executing.
Context	All run and their hashes are merged. A key set by two handlers goes to the last one registered, and the collision is reported through `Rails.error`.
Lifecycle	All run in order. Return values are ignored.

One consequence worth planning for: because any handler can veto, a validate handler should say why it rejected in the message, and a lifecycle handler should not assume it is the only observer of the event.

Handlers are not isolated from each other. An exception raised in one propagates out of the workflow, later handlers on that hook never run, and an open transaction rolls back — a raise in an after_item_added handler leaves the customer’s item not added at all.If your handler does something optional (analytics, a nice-to-have notification), rescue inside it so a failure in your code can’t undo someone else’s order. Work that is genuinely allowed to fail belongs in an event subscriber, not a hook.

The three kinds of hooks

Lifecycle hooks — react to something that happened

Named in the past tense (after_item_added, after_cancel, after_create). They run after the work is done. Return values are ignored; you cannot change the outcome.

class MyStore::NotifyWarehouse
  def call(workflow)
    WarehouseApi.notify(workflow.fulfillment.number)
  end
end

Spree.hooks.register('fulfillments.create.after_create', 'MyStore::NotifyWarehouse')

Note that some lifecycle hooks run inside the flow’s database transaction (after_item_added, after_cancel). That’s deliberate — it lets you write related records atomically with the change. It also means slow work does not belong there: use an event subscriber for emails, webhooks and other eventual work.

Validation hooks — veto before the work happens

Always called validate. They run before anything is written, so rejecting costs nothing — no rollback, no partial state, no money moved. Call reject! on the workflow to stop the flow:

module MyStore
  class LimitReturnWindow
    def call(workflow)
      return if workflow.order.completed_at > 30.days.ago

      workflow.reject!('This order is outside the 30-day return window.')
    end
  end
end

The caller receives a normal failure result — no exception reaches your controller:

result = Spree.return_create_workflow.call(order: order, items: items)
result.success?    # => false
result.error.to_s  # => "This order is outside the 30-day return window."
result.error.value # => ActiveModel::Errors — the rejection, field by field

Reject from validate hooks, not from after_* hooks. Rejecting late still rolls the database back, but it cannot undo work that already left the system — carts.complete.before_finalize runs after the customer’s card was charged, so rejecting there rolls back the order while the charge stands. If you need to stop a flow, validate is the place.

Context hooks — feed data into a calculation

Named imperatively (set_promotion_context, set_tax_line_context, get_provider_data). They run before a calculation so you can contribute data to it. Your handler returns a hash. Spree merges the hashes from every registered handler and hands the result to the workflow:

module MyStore
  class TaxExemption
    def call(workflow)
      certificate = workflow.cart.customer&.tax_exemption_certificate
      return {} if certificate.blank?

      { exemption_certificate: certificate.number }
    end
  end
end

Spree.hooks.register('carts.recalculate_totals.set_tax_line_context', 'MyStore::TaxExemption')

Handlers stay independent — there is no shared object to mutate and no ordering to reason about. A handler returning anything other than a hash contributes nothing, so lifecycle-style handlers are harmless if registered here by mistake. If two handlers set the same key, the last registered one wins and the collision is reported through Rails.error so it’s visible rather than mysterious.

Available hooks

Workflow key	Hook	Kind	When it runs
`carts.add_item`	`validate`	validate	Before the line item is built
`carts.add_item`	`after_item_added`	lifecycle	After the item is saved and totals recalculated (in transaction)
`carts.upsert_items`	`validate`	validate	Once per item, immediately before that item is applied — quantity edits, removals and bulk payloads. Earlier items in the batch may already be written
`carts.upsert_items`	`after_items_upserted`	lifecycle	After the batch is applied and the cart recalculated once (in transaction)
`carts.complete`	`validate`	validate	After checkout requirements pass, before the order is created
`carts.complete`	`before_finalize`	lifecycle	After payment, before the order is placed
`carts.complete`	`after_finalize`	lifecycle	After the order is placed
`carts.merge`	`validate`	validate	Before any items move between carts
`carts.merge`	`after_merge`	lifecycle	After the carts are folded together
`carts.recalculate`	`set_promotion_context`	context	Before promotions are evaluated
`carts.recalculate`	`after_recalculate`	lifecycle	After the cart is fully repriced
`carts.recalculate_totals`	`set_tax_line_context`	context	Before tax is estimated
`orders.cancel`	`before_cancel`	validate	Before the cancellation is recorded
`orders.cancel`	`after_cancel`	lifecycle	With the cancellation, in transaction
`orders.resume`	`before_resume`	validate	Before the order is un-cancelled
`orders.resume`	`after_resume`	lifecycle	With the status flip, in transaction
`fulfillments.create`	`validate`	validate	Before the order is locked
`fulfillments.create`	`get_provider_data`	context	Before the fulfillment is built
`fulfillments.create`	`after_create`	lifecycle	After the fulfillment is created and totals recalculated
`payments.capture`	`validate`	validate	Before the gateway is called
`payments.capture`	`before_capture`	lifecycle	Immediately before the gateway call
`payments.capture`	`after_capture`	lifecycle	After a successful capture
`payments.refund`	`validate`	validate	Before the refund record exists
`payments.refund`	`before_refund`	lifecycle	Immediately before the gateway call
`payments.refund`	`after_refund`	lifecycle	After a successful refund
`payments.handle_webhook`	`after_handle`	lifecycle	After the gateway callback is processed
`customers.create`	`validate`	validate	After the customer is built, before it is saved — the registration-policy veto (bot screening, B2B approval)
`customers.create`	`after_create`	lifecycle	After the customer is created and the newsletter subscriber linked
`products.create`	`validate`	validate	After the product is built, before it is saved — fires for the Admin API, CSV imports and seeds alike
`products.create`	`after_create`	lifecycle	After the product is saved (in transaction)
`products.update`	`validate`	validate	With the pending attributes assigned, so `product.changes` describes the edit
`products.update`	`after_update`	lifecycle	After the product is saved (in transaction)
`products.destroy`	`validate`	validate	Before the product is soft-deleted — refuse a deletion your store shouldn’t allow
`products.destroy`	`after_destroy`	lifecycle	After the soft-delete, for host cleanup (in transaction)
`products.activate`	`validate`	validate	Before the product goes on sale — the place to require an image, a price or a category
`products.activate`	`after_activate`	lifecycle	After the status is written (in transaction)
`products.archive`	`validate`	validate	Before the product is taken off sale
`products.archive`	`after_archive`	lifecycle	After the status is written (in transaction)
`products.draft`	`validate`	validate	Before the product returns to draft
`products.draft`	`after_draft`	lifecycle	After the status is written (in transaction)
`gift_cards.apply`	`validate`	validate	Before a card is drawn against — who may spend a card, on what, up to how much
`gift_cards.apply`	`after_apply`	lifecycle	After the store credit and payment exist (in transaction)
`gift_cards.remove`	`validate`	validate	Before a card is taken back off an order
`gift_cards.remove`	`after_remove`	lifecycle	After the balance is returned to the card (in transaction)
`gift_cards.redeem`	`validate`	validate	Before the card is recorded as spent
`gift_cards.redeem`	`after_redeem`	lifecycle	After the status is written (in transaction)
`gift_cards.cancel`	`validate`	validate	Before a card is voided
`gift_cards.cancel`	`after_cancel`	lifecycle	After the card is voided (in transaction)
`price_lists.create`	`validate`	validate	After the list is built, before it is saved
`price_lists.create`	`after_create`	lifecycle	After the list and its product membership exist (in transaction)
`price_lists.update`	`validate`	validate	With the pending attributes assigned, before anything is written
`price_lists.update`	`after_update`	lifecycle	After membership and price overrides are applied (in transaction)
`price_lists.activate`	`validate`	validate	Before a price list takes effect
`price_lists.activate`	`after_activate`	lifecycle	After the list goes live or is scheduled (in transaction)
`price_lists.deactivate`	`validate`	validate	Before a price list stops applying
`price_lists.deactivate`	`after_deactivate`	lifecycle	After the list is switched off (in transaction)
`invitations.accept`	`validate`	validate	After the expiry and invitee checks pass, before any access is granted
`invitations.accept`	`after_accept`	lifecycle	After the role is granted and the invitation marked accepted (in transaction)
`imports.start_mapping`	`validate`	validate	Before the uploaded file is read
`imports.start_mapping`	`after_start_mapping`	lifecycle	After the column mappings are built (in transaction)
`imports.complete_mapping`	`validate`	validate	Before the mapping is accepted — refuse a mapping your store considers incomplete
`imports.complete_mapping`	`after_complete_mapping`	lifecycle	After the mapping is accepted, before row creation is dispatched (in transaction)
`imports.start_processing`	`validate`	validate	Before the import starts working through its rows
`imports.start_processing`	`after_start_processing`	lifecycle	After the status is written (in transaction)
`imports.complete`	`validate`	validate	Before the import is closed out
`imports.complete`	`after_complete`	lifecycle	After the import is completed and the store touched (in transaction)
`imports.retry_failed_rows`	`validate`	validate	Before failed rows are queued again
`imports.retry_failed_rows`	`after_retry`	lifecycle	After the import returns to processing, before re-dispatch (in transaction)

before_cancel and before_resume accept reject! like a validate hook. Draft-order editing in the admin uses twin workflows with their own keys — orders.add_item, orders.upsert_items, orders.recalculate, orders.recalculate_totals — carrying the same hooks as their cart counterparts. Register against the cart key for storefront carts, the order key for admin edits, or both.

carts.add_item adds to a quantity; carts.upsert_items sets it, and is what a quantity edit, a removal (quantity 0) and a bulk item payload all run through. A rule about what may be in a cart therefore belongs on both keys — the readers are the same (cart, variant, quantity), so one handler class registers against each.upsert_items is also the one flow where a rejection is not fatal on the storefront: the vetoed item is skipped, the rest of the batch applies, and what was dropped comes back in the cart’s warnings. A customer restoring a saved cart keeps whatever is still purchasable. Admin order edits behave the opposite way — the whole edit fails — because a silently dropped row is worse than a failed request when a merchant is editing.

Inspect what’s available at runtime:

Spree.hooks.workflows              # => { 'carts.add_item' => 'Spree::Carts::AddItem', ... }
Spree::Carts::Complete.declared_hooks  # => [:validate, :before_finalize, :after_finalize]
Spree.hooks.keys                   # => registered keys
Spree.hooks.validate!              # => true, or raises on a bad registration

Writing your own workflow

Most extensions only need hooks. Write a workflow when you’re adding a new multi-step operation of your own — one with external calls, compensation, or extension points for others.

module MyStore
  class Subscriptions::Renew < Spree::Workflow
    hooks :validate, :after_renew

    attr_reader :order

    # The method signature is the contract — Ruby raises on a missing or
    # unknown keyword, and a bare `super` turns each parameter into a reader.
    #
    # @param subscription [MyStore::Subscription]
    # @param renewed_at [Time, nil]
    def perform(subscription:, renewed_at: nil)
      super

      step :ensure_renewable
      run_hooks :validate

      ApplicationRecord.transaction do
        step :build_order, on_flow_failure: :discard_order
        step :extend_period
      end

      external_step :charge_customer

      run_hooks :after_renew
      subscription.publish_event('subscription.renewed')
      success(order)
    end

    private

    def ensure_renewable
      failure(subscription, :not_active) unless subscription.active?
    end

    def build_order
      @order = MyStore::Subscriptions::BuildOrder.call(subscription: subscription).value
    end

    def extend_period
      subscription.update!(renews_at: (renewed_at || Time.current) + 1.month)
    end

    def charge_customer
      Spree.payment_capture_workflow.call(payment: order.payments.last)
    end

    # Runs if a later step fails after the transaction committed.
    def discard_order
      order&.destroy
    end
  end
end

The whole vocabulary:


`step :name`	Runs the private method of that name
`external_step :name`	Same, but refuses to run inside a database transaction this workflow opened — use it for every network call
`with: -> { ... }`	Delegates a step to a swappable collaborator, keyword arguments sliced from the workflow’s readers
`on_flow_failure: :name`	Names the undo for a step, run in reverse if a later step fails
`run_hooks :name`	Dispatches a declared hook; returns the merged hash from context handlers
`failure(value, error)`	Aborts the flow — rolls back an open transaction and returns a failure result
`reject!`	The same, named for hook handlers vetoing a flow — carries `workflow.errors`
`halt!(value)`	Successful early exit (not valid inside a transaction the workflow opened)
`hooks :a, :b`	Declares the extension points this workflow dispatches

Everything else is ordinary Rails — ApplicationRecord.transaction, with_lock, if, rescue, publish_event. Two rules worth internalising: Network calls never share a database transaction. That’s what external_step enforces. A gateway call inside a transaction holds a database connection open across a network round trip, and a timeout leaves your database and the payment processor disagreeing about what happened. Models get a plain status string, not a state machine. Transitions are workflows: MyStore::Subscriptions::Cancel.call(...), not subscription.cancel!. Transition callbacks hide side effects inside a save, cannot take arguments, and have no compensation story. As of 6.0 this is not just advice for new models — Spree has no state machines left. Every status a record can hold is declared with Spree::HasStatus, and every move between two of them is a workflow you can hook.

Statuses

Spree::HasStatus declares the statuses a model can hold:

class MyStore::Subscription < Spree.base_class
  include Spree::HasStatus
  has_status :trialing, :active, :paused, :canceled, default: :trialing
end

That gives you an inclusion validation, a predicate per value (subscription.paused?), a scope per value (Subscription.paused) and with_status(:active, :trialing) for several at once. It deliberately does not give you a transition graph — deciding which moves are legal is the workflow’s job, which is what lets a transition take arguments, call out to a gateway outside a transaction, and undo itself when a later step fails. Statuses are additive, so an extension can add its own without reopening the model:

Spree::GiftCard.add_status(:on_hold, after: :active)

A custom status needs a custom workflow to move records into it. That is the design, not a gap: a central place validating transitions would be a state machine again.

has_status never overwrites something the model already defines. Where a status name means more than the column value — Spree::GiftCard#active? also requires the card not to have expired, and Spree::GiftCard.active includes partially redeemed cards — the model’s own definition wins and the generated one is skipped.

Moving a record between statuses

Call the workflow, not the model:

result = Spree.product_archive_workflow.call(product: product)
result.success?

Spree ships one workflow per transition — Spree::Products::Activate, Spree::GiftCards::Redeem, Spree::Imports::Complete, and so on — each with its own validate and after_* hooks, all in Available hooks above. Because the write and the event it publishes happen in the same place, registering against a hook is enough to see every transition, wherever it was triggered from.

Observability

Every step emits an ActiveSupport::Notifications event, so your APM sees the flow without extra instrumentation:

ActiveSupport::Notifications.subscribe('step.spree_workflow') do |*, payload|
  Rails.logger.info("#{payload[:workflow]}##{payload[:step]}")
end

Choosing an extension point

You want to	Use
Stop an operation from happening	A `validate` hook
Add data to a pricing or tax calculation	A context hook
Do something after an operation, in the same transaction	A lifecycle hook
Send an email, call a webhook, update a search index	An event subscriber
Replace an operation entirely	Dependencies
Add a brand-new multi-step operation	Your own workflow

Reach for the smallest one that does the job. A hook survives Spree upgrades; a replaced class has to be kept in sync with every release.

Tutorial

Admin Panel

Customization Reference

Overview

Calling them

Extending a workflow with hooks

Every hook can have many handlers

The three kinds of hooks

Lifecycle hooks — react to something that happened

Validation hooks — veto before the work happens

Context hooks — feed data into a calculation

Available hooks

Writing your own workflow

Statuses

Moving a record between statuses

Observability

Choosing an extension point

​Overview

​Calling them

​Extending a workflow with hooks

​Every hook can have many handlers

​The three kinds of hooks

​Lifecycle hooks — react to something that happened

​Validation hooks — veto before the work happens

​Context hooks — feed data into a calculation

​Available hooks

​Writing your own workflow

​Statuses

​Moving a record between statuses

​Observability

​Choosing an extension point

Overview

Calling them

Extending a workflow with hooks

Every hook can have many handlers

The three kinds of hooks

Lifecycle hooks — react to something that happened

Validation hooks — veto before the work happens

Context hooks — feed data into a calculation

Available hooks

Writing your own workflow

Statuses

Moving a record between statuses

Observability

Choosing an extension point