State Machines

Solidus uses the state_machines gem internally for defining the state-related logic. While most of the e-commerces don't need to customize the default state machines, Solidus allows providing a custom implementation for the following models' attributes:

State machines customization

If you need to customize an existing state machine, create a module containing your custom definition:

module MyStore
  module StateMachines
    module ReturnAuthorization
      extend ActiveSupport::Concern

      included do
        state_machine initial: :authorized do
          before_transition to: :canceled, do: :cancel_return_items

          event :cancel do
            transition to: :canceled, from: :authorized

          event :custom_event do
            transition to: :custom_state, from: :authorized


Then assign your custom module name to the state machines registry:

Spree.config do |config|
  # Return authorization status
  config.state_machines.return_authorization = '::MyStore::StateMachines::ReturnAuthorization'

  # Other configurable state machines available:

  # Return Item reception status
  # config.state_machines.return_item_reception = '<your-custom-module-name>'

  # Return Item acceptance status
  # config.state_machines.return_item_acceptance = '<your-custom-module-name>'

  # Payment status
  # config.state_machines.payment = '<your-custom-module-name>'

  # Inventory Unit status
  # config.state_machines.inventory_unit = '<your-custom-module-name>'

  # Checkout status
  # config.state_machines.order = '<your-custom-module-name>'


This will include your custom module into Spree::ReturnAuthorization class instead of the Solidus provided one.

Using different state machines implementations

You can also completely replace state_machines with your own implementation. Just make sure to expose the following API.

For each event, the state_machines gem dynamically implements the following instance methods:

  • #<event_name>
  • #<event_name>!
  • #can_<event_name>?

for example, having a state machine event named cancel, you'll need to implement:

  • #cancel
  • #cancel!
  • #can_cancel?

For each state, the following instance method is implemented:

  • #<state_name>?

for example, having a state named canceled, your custom implementation should expose:

  • #canceled?


Solidus is an open source platform supported by the community. We encourage everyone using Solidus to contribute back to the documentation and the code.

If you’re interested in contributing to the docs, get started with the contributing guidelines. If you see something that needs fixing and can’t do it yourself, please send us an email.