@spree/docs 0.1.141 → 0.1.143

package/dist/developer/customization/api.md

@@ -3,7 +3,7 @@ title: Customizing the Spree API
 description: Add new Store API endpoints, customize existing JSON responses with serializer decorators, and extend Spree's REST API to fit your storefront needs.
 ---
 
-Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](/api-reference).
+Before you start customizing Spree API endpoints, make sure you reviewed all existing API endpoints in the [Spree API docs](../../api-reference/admin-api/endpoints.md).
 
 For a step-by-step walkthrough of adding a complete new resource (model, serializer, controller, routes), see the [API tutorial](../tutorial/api.md).
 

package/dist/developer/customization/decorators.md

@@ -532,4 +532,3 @@ end
 - [Admin Partials](../admin/extending-ui.md) - Extend admin UI without view decorators
 - [Extending Core Models Tutorial](../tutorial/extending-models.md) - Step-by-step guide to connecting custom models with Spree core
 - [Customization Overview](quickstart.md) - General customization patterns
-- [Logic Customization](logic.md) - Customizing business logic

package/dist/developer/customization/dependencies.md

@@ -5,7 +5,16 @@ section: customization
 
 ## Overview
 
-With Dependencies, you can easily replace parts of Spree core with your custom code. You can replace [Services](https://github.com/spree/spree/tree/master/core/app/services/spree), CanCanCan Abilities (used for [Permissions](permissions)), and [API Serializers](https://github.com/spree/spree/tree/master/api/app/serializers/spree/v2) (used for generating JSON API responses).
+With Dependencies, you can replace parts of Spree core with your custom code:
+[Services and Workflows](workflows.md), CanCanCan
+Abilities (used for [Permissions](permissions.md)), and API Serializers (used for
+generating JSON API responses).
+
+> **TIP:** Replacing a whole class means keeping your copy in sync with every Spree
+> release. If you only need to run code inside an existing flow — validating,
+> reacting, or contributing data to a calculation — use a
+> [hook](workflows.md#extending-a-workflow-with-hooks)
+> instead. Hooks survive upgrades.
 
 ## Application (global) customization
 
@@ -14,50 +23,68 @@ This will change every aspect of the application (both APIs, Admin Panel, and St
 In your `config/initializers/spree.rb` file, you can set the following:
 
 ```ruby
-Spree.cart_add_item_service = MyAddToCartService
+Spree.cart_update_service = MyStore::CartUpdate
 ```
 
 or using the block syntax:
 
 ```ruby
 Spree.dependencies do |dependencies|
-  dependencies.cart_add_item_service = MyAddToCartService
+  dependencies.cart_update_service = MyStore::CartUpdate
 end
 ```
 
 Now let's create your custom service.
 
 ```bash
-mkdir -p app/services && touch app/services/my_add_to_cart_service.rb
+mkdir -p app/services/my_store && touch app/services/my_store/cart_update.rb
 ```
 
 And add the following code to it:
 
 ```ruby
-class MyAddToCartService < Spree::Cart::AddItem
-  def call(order:, variant:, quantity: nil, metadata: {}, options: {})
-    ApplicationRecord.transaction do
-      run :add_to_line_item
-      run Spree.cart_recalculate_service
-      run :update_in_external_system
+module MyStore
+  class CartUpdate < Spree::Carts::Update
+    def call(cart:, params:)
+      result = super
+
+      MyStore::ErpSync.push(result.value) if result.success?
+
+      result
     end
   end
+end
+```
+
+Inheriting and calling `super` keeps Spree's behaviour and adds yours around it,
+which is usually what you want — a full rewrite means re-implementing logic that
+changes between releases.
+
+### Replacing a workflow
 
-  private
+Workflow-backed seams end in `_workflow` (`cart_add_item_workflow`,
+`carts_complete_workflow`, `payment_capture_workflow`, …). A replacement
+subclasses the workflow and overrides `perform`:
 
-  def update_in_external_system(new_order_line_item)
-    # Your custom logic here
+```ruby
+module MyStore
+  class AddItem < Spree::Carts::AddItem
+    def perform(variant:, cart: nil, **rest)
+      super
+
+      # your logic, then the standard result
+    end
   end
 end
-```
 
-This code will:
+Spree.cart_add_item_workflow = MyStore::AddItem
+```
 
-1. Inherit from `Spree::Cart::AddItem`
-2. Override the `call` method to add your custom logic
-3. Call `run :add_to_line_item` to add the item to the cart
-4. Call `run Spree.cart_recalculate_service` to recalculate the cart (returns the resolved class)
-5. Call `run :update_in_external_system` to execute your custom logic, eg. updating Order in an external system such as ERP
+> **NOTE:** Before writing this, check whether a
+> [hook](workflows.md#available-hooks) covers your case —
+> `carts.add_item.validate` and `carts.add_item.after_item_added` handle most
+> reasons people replace this class, and they don't need maintaining across
+> upgrades.
 
 ## Using dependencies in your code
 
@@ -65,7 +92,7 @@ When you need to use a dependency in your code, you can access it directly via t
 
 ```ruby
 # Returns the resolved class (not a string)
-Spree.cart_add_item_service.call(order: order, variant: variant, quantity: 1)
+Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 1)
 
 # For API dependencies, use the Spree.api accessor
 Spree.api.storefront_cart_serializer.new(order).serializable_hash
@@ -99,7 +126,7 @@ end
 
 This will change the serializer in this API endpoint to `MyNewAwesomeCartSerializer` and also it will swap the default `add_item_service` to `MyNewAwesomeAddItemToCart`.
 
-Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/master/api/app/controllers/spree/api/v2) to see what you can replace.
+Different API endpoints can have different dependency injection points. You can review their [source code](https://github.com/spree/spree/tree/main/api/app/controllers/spree/api/v3) to see what you can replace.
 
 ## API level customization
 
@@ -117,7 +144,7 @@ This will swap the default Cart serializer and Add Item to Cart service for your
 You can mix and match both global and API-level customizations:
 
 ```ruby
-Spree.cart_add_item_service = MyNewAwesomeAddItemToCart
+Spree.cart_add_item_workflow = MyNewAwesomeAddItemToCart
 Spree.api.storefront_cart_add_item_service = AnotherAddItemToCart
 ```
 
@@ -137,9 +164,9 @@ This will output all dependencies with their current values:
 
 ```
 [CORE]
-cart_add_item_service           Spree::Cart::AddItem
-cart_create_service             Spree::Cart::Create
-cart_recalculate_service        Spree::Cart::Recalculate [OVERRIDDEN]
+cart_add_item_workflow          Spree::Carts::AddItem
+carts_create_service            Spree::Carts::Create
+cart_recalculate_workflow       Spree::Carts::Recalculate [OVERRIDDEN]
 ...
 
 [API]
@@ -164,10 +191,10 @@ This shows only the dependencies that have been customized, along with their ori
 
 ```
 [Core OVERRIDES]
-cart_recalculate_service  Spree::Cart::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
+cart_recalculate_workflow  Spree::Carts::Recalculate -> MyApp::CartRecalculate (config/initializers/spree.rb:15)
 
 [API OVERRIDES]
-storefront_cart_add_item_service  Spree::Cart::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
+storefront_cart_add_item_service  Spree::Carts::AddItem -> MyApp::CartAddItem (config/initializers/spree.rb:20)
 ```
 
 ### Validate all dependencies
@@ -181,7 +208,7 @@ This validates that all dependencies can be resolved to valid classes. If any de
 ```
 ..........F.........
 1 invalid dependencies:
-  [Core] cart_add_item_service: uninitialized constant NonExistentClass
+  [Core] cart_add_item_workflow: uninitialized constant NonExistentClass
 ```
 
 ## Programmatic introspection
@@ -191,14 +218,14 @@ You can also inspect dependencies programmatically:
 ```ruby
 # Check all current values
 Spree::Dependencies.current_values
-# => [{name: :cart_add_item_service, current: MyApp::CartAddItem, default: 'Spree::Cart::AddItem', overridden: true}, ...]
+# => [{name: :cart_add_item_workflow, current: MyApp::CartAddItem, default: 'Spree::Carts::AddItem', overridden: true}, ...]
 
 # Check if a specific dependency is overridden
-Spree::Dependencies.overridden?(:cart_add_item_service)
+Spree::Dependencies.overridden?(:cart_add_item_workflow)
 # => true
 
 # Get override information (where it was set)
-Spree::Dependencies.override_info(:cart_add_item_service)
+Spree::Dependencies.override_info(:cart_add_item_workflow)
 # => {value: MyApp::CartAddItem, source: "config/initializers/spree.rb:15", set_at: 2024-01-15 10:30:00}
 
 # Validate all dependencies resolve to valid classes
@@ -206,18 +233,43 @@ Spree::Dependencies.validate!
 # => true (or raises Spree::DependencyError)
 ```
 
+## Renamed seams in Spree 6.0
+
+Seams backed by a [workflow](workflows.md) were renamed
+from `*_service` to `*_workflow` in 6.0:
+
+| Legacy name | Current name |
+|---|---|
+| `cart_add_item_service` | `cart_add_item_workflow` |
+| `cart_recalculate_service` | `cart_recalculate_workflow` |
+| `carts_complete_service` | `carts_complete_workflow` |
+| `cart_merge_strategy` | `cart_merge_workflow` |
+| `order_cancel_service` | `order_cancel_workflow` |
+| `order_complete_service` | `order_complete_workflow` |
+| `fulfillment_create_service` | `fulfillment_create_workflow` |
+| `payments_handle_webhook_service` | `payments_handle_webhook_workflow` |
+
+> **WARNING:** The legacy names stay readable for one release, but **assigning to one no longer
+> has any effect** — the override is recorded and a deprecation warning names the
+> seam to port to. A class written against the old service contract isn't
+> interchangeable with the workflow the new call sites use, so applying it
+> silently would break checkout in ways that are hard to trace.
+> 
+> If you override any of these, move to the `*_workflow` name and make sure your
+> class subclasses the workflow. The legacy names are removed in Spree 6.1.
+
 ## Backwards compatibility
 
 The legacy string-based syntax is still supported for backwards compatibility:
 
 ```ruby
 # Legacy syntax (still works)
-Spree::Dependencies.cart_add_item_service = 'MyAddToCartService'
-result = Spree::Dependencies.cart_add_item_service.constantize
+Spree::Dependencies.carts_create_service = 'MyStore::CartCreate'
+result = Spree::Dependencies.carts_create_service.constantize
 
 # New syntax (recommended)
-Spree.cart_add_item_service = MyAddToCartService
-result = Spree.cart_add_item_service
+Spree.carts_create_service = MyStore::CartCreate
+result = Spree.carts_create_service
 ```
 
 Both syntaxes can coexist, but the new syntax is recommended as it's more concise and provides better error messages at assignment time.

package/dist/developer/customization/workflows.md

@@ -0,0 +1,383 @@
+---
+title: Services & Workflows
+section: customization
+---
+
+## 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:
+
+```ruby
+result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant, quantity: 2)
+
+if result.success?
+  line_item = result.value
+else
+  puts result.error.value
+end
+```
+
+Never raise on expected failures — check `result.success?`. See
+[Dependencies](dependencies.md) 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`:
+
+```ruby
+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:
+
+```ruby
+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:
+
+```ruby
+module MyStore
+  class CheckPurchaseLimit
+    def call(workflow)
+      # every #perform keyword is a reader: cart, variant, quantity, ...
+      return if workflow.quantity <= 10
+
+      workflow.reject!('You can order at most 10 of this item.')
+    end
+  end
+end
+```
+
+> **NOTE:** 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.
+
+```ruby
+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.
+
+> **WARNING:** 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](../core-concepts/events.md), 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.
+
+```ruby
+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](../core-concepts/events.md) 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:
+
+```ruby
+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:
+
+```ruby
+result = Spree.cart_add_item_workflow.call(cart: cart, variant: variant)
+result.success?    # => false
+result.error.value # => "You can order at most 10 of this item."
+```
+
+> **WARNING:** 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:
+
+```ruby
+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.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 |
+
+`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.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.
+
+Inspect what's available at runtime:
+
+```ruby
+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.
+
+```ruby
+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!(message)` | The same, named for hook handlers vetoing a flow |
+| `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.
+
+**New 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.
+
+## Observability
+
+Every step emits an `ActiveSupport::Notifications` event, so your APM sees the
+flow without extra instrumentation:
+
+```ruby
+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](../core-concepts/events.md) |
+| Replace an operation entirely | [Dependencies](dependencies.md) |
+| 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.