Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
---
title: Events
description: Reacting to things that happen in Spree — an order placed, a payment taken, stock running out — without modifying core code.
---
## Overview
Something happens in a store — an order is placed, a payment clears, a product sells out — and you want something else to happen: notify a warehouse, post to a channel, update a spreadsheet.
Events are how you attach that behaviour without editing Spree. Spree announces what happened; your code decides what to do about it.
```mermaid
flowchart LR
Action["Order is placed"] --> Event["order.placed"]
Event --> Sub["Your subscriber<br/>(in-app)"]
Event --> Hook["Webhook<br/>(external system)"]
```
There are two ways to listen, and which you want depends on where your code lives:
| | Use it when |
|---|---|
| **[Webhooks](/developer/core-concepts/webhooks)** | The thing reacting is a separate system — a Next.js app, an ERP, an automation tool |
| **Subscribers** | The reaction belongs inside the Spree application itself |
If you're building a headless storefront, **webhooks are almost certainly what you want**. Subscribers are for when you're running Spree as your own application and want to add behaviour to it.
## What Spree announces
Most records announce their own lifecycle:
| Event | When |
|---|---|
| `<resource>.created` | A record is created |
| `<resource>.updated` | It changes |
| `<resource>.deleted` | It's removed |
Those exist for orders, carts, products, variants, customers, payments, fulfillments, returns, media, price changes and more.
On top of that, meaningful business moments get their own events:
| Event | Meaning |
|---|---|
| `order.placed` | An order was placed — one per order, so a checkout that split across several sellers publishes one per seller |
| `order_group.completed` | A checkout that split finished — one event for the whole purchase |
| `order.paid` | Payment is settled in full |
| `order.canceled` | The order was cancelled |
| `order.fulfilled` / `order.delivered` | Everything has shipped / arrived |
| `payment.completed` / `payment.voided` | A payment succeeded / was released |
| `fulfillment.fulfilled` / `fulfillment.canceled` | A parcel went out / was stood down |
| `product.out_of_stock` / `product.back_in_stock` | Availability flipped |
| `return.received` / `return.refunded` | A return arrived / was refunded |
| `import.completed` | An import finished |
For the full list of events and their payloads, see [Webhook Events & Payloads](/api-reference/webhooks-events).
The distinction matters when choosing what to listen for. `order.updated` fires whenever anything about an order changes — including an admin editing a note. `order.placed` fires once, when a customer actually bought something. Sending a confirmation email on the wrong one is how customers receive nine copies.
## What an event carries
An event carries the record it's about, serialized:
```json Event payload
{
"id": "or_86Rf07xd4z",
"number": "R123456789",
"payment_status": "paid",
"total": "135.60",
"email": "[email protected]"
}
```
IDs are the same prefixed IDs the API uses, so you can take an ID out of an event and fetch the full record without translating anything.
## Reacting in another system
Point a webhook at your endpoint and subscribe it to the events you care about. That's covered fully in [Webhooks](/developer/core-concepts/webhooks) — including signature verification, which you should not skip.
## Reacting inside Spree
A subscriber is a small class that names the events it wants and does something when one arrives.
<CodeGroup>
```bash Spree CLI (Docker)
spree generate subscriber OrderPlaced order.placed
```
```bash Without Spree CLI
bin/rails g spree:subscriber OrderPlaced order.placed
```
</CodeGroup>
The generator writes the class, a test, and — the step that's easy to forget — registers it.
```ruby server/app/subscribers/order_placed_subscriber.rb
class OrderPlacedSubscriber < Spree::Subscriber
subscribes_to 'order.placed'
def handle(event)
order = Spree::Order.find_by_prefix_id(event.payload['id'])
return unless order
WarehouseClient.new.submit(order)
end
end
```
A subscriber can listen to several events, or to a whole family:
```ruby server/app/subscribers/order_placed_subscriber.rb
subscribes_to 'order.placed', 'order.canceled'
subscribes_to 'order.*'
```
Subscribers must be registered — they aren't discovered automatically, because a subscriber that starts running because of where its file sits is hard to reason about:
```ruby server/config/initializers/spree.rb
Rails.application.config.after_initialize do
Spree.subscribers << OrderPlacedSubscriber
end
```
### Subscribers run in the background
By default a subscriber runs as a background job, so a slow API call in your code doesn't slow down the customer's checkout — and a failure doesn't roll back their order.
That's almost always what you want. If you genuinely need to run inside the same transaction, you can ask to:
```ruby server/app/subscribers/order_placed_subscriber.rb
subscribes_to 'order.placed', async: false
```
<Warning>
A synchronous subscriber runs while the customer waits, so a slow one slows their checkout. An exception in it is reported to `Rails.error` and swallowed in production, but re-raised in development and test so you notice it. Reserve it for work that must happen immediately, and keep it fast.
</Warning>
## Publishing your own events
Anything in your own code can announce something, and subscribers and webhooks treat it like any built-in event. Declare the event on the model first, then publish it:
```ruby server/config/initializers/spree_events.rb
Rails.application.config.to_prepare do
Spree::Order.publishes_event :flagged_for_review
end
```
```ruby server/app/services/fraud_check.rb
order.publish_event('order.flagged_for_review')
```
Useful when your own domain has moments worth reacting to — a fraud check completing, an approval granted.
Every event Spree publishes is declared this way, which is what lets the admin dashboard's webhook picker, the [webhook events endpoint](/developer/core-concepts/webhooks#event-subscriptions) and the typed events in `@spree/sdk/webhooks` list it. Publishing an event nobody declared raises an error in development and test, so a typo is caught before it ships; in production it is logged and delivered anyway.
The payload is the model's Store API serializer, as for built-in events. To send something else, pass a serializer of your own: `publishes_event :flagged_for_review, serializer: 'MyApp::FraudFlagEventSerializer'`. Keep it to what a customer could see; back-office fields belong behind the Admin API. Facts about the event rather than the record, such as who triggered it, go in its metadata: `order.publish_event('order.flagged_for_review', nil, rule: 'velocity')`.
## Guidance
**Listen for the specific event.** `order.placed` rather than `order.updated` with a status check.
**Assume events can arrive more than once.** A retry after a network blip can redeliver. Make handlers safe to run twice — check whether you've already acted before acting.
**Don't chain long sequences of subscribers.** When one event triggers a subscriber that triggers another, working out what happened after the fact becomes archaeology. Prefer one handler that does the sequence.
**Keep failures contained.** A subscriber that raises shouldn't take down anything else. Handle your own errors and log them.
## Related
- [Webhooks](/developer/core-concepts/webhooks) — reacting from outside Spree
- [Orders](/developer/core-concepts/orders) — the order lifecycle these events describe
- [Imports & Exports](/developer/core-concepts/imports-exports) — completion events for bulk work