Events
Reference for all events dispatched by Shopper during order, product, and cart lifecycle operations.
Shopper dispatches events at key moments in the order, product, and cart lifecycle. These events allow you to hook into the system and add custom behavior like sending notifications, syncing with external services, updating analytics, or triggering workflows without modifying any Shopper code.
The events on this page are organized by domain across two namespaces:
Shopper\Core\Events: order and product eventsShopper\Cart\Events: cart events
The admin panel also dispatches events that this page does not cover: Shopper\Events\TwoFactor\TwoFactorAuthenticationEnabled when a user turns on two-factor authentication, Shopper\Events\LoadShopper on every admin request, and Shopper\Sidebar\SidebarBuilder when it builds the sidebar.
use Shopper\Core\Events\Orders\OrderCompleted;
use Shopper\Core\Events\Orders\OrderPaid;
use Shopper\Core\Events\Products\ProductCreated;Listening to Events
Register listeners with Laravel's event discovery (a listener in app/Listeners whose handle method type-hints the event), with Event::listen() in a service provider, or in the $listen array of an EventServiceProvider:
use Shopper\Core\Events\Orders\OrderCompleted;
use Shopper\Core\Events\Orders\OrderPaid;
protected $listen = [
OrderPaid::class => [
GenerateInvoice::class,
SendPaymentConfirmation::class,
],
OrderCompleted::class => [
SendOrderCompletedEmail::class,
],
];Every event carries the relevant model as a public property, accessible directly in your listener:
use Shopper\Core\Events\Orders\OrderPaid;
class GenerateInvoice
{
public function handle(OrderPaid $event): void
{
$order = $event->order;
$order->load('items', 'customer', 'billingAddress');
Invoice::generate($order);
}
}Order Events
Order events cover the full lifecycle of a purchase, from creation to completion, cancellation, or archival.
Available Events
| Event | Payload | Trigger |
|---|---|---|
OrderCreated | Order $order | Order is inserted in the database |
OrderItemCreated | OrderItem $orderItem | Order item is inserted in the database |
OrderPaid | Order $order | Admin marks order as paid |
OrderCompleted | Order $order | Admin marks order as completed |
OrderShipped | Order $order | All items reach shipped status |
OrderCancelled | Order $order | Admin cancels the order |
OrderArchived | Order $order | Admin archives the order |
OrderDeleted | Order $order | Order is being deleted (soft or force delete) |
OrderNoteAdded | Order $order | Admin adds a note to the order |
All order events except OrderItemCreated carry a single public Order $order property. It is typed with the Shopper\Core\Models\Contracts\Order contract, so you receive an instance of the model set in config('shopper.models.order'). OrderItemCreated carries public OrderItem $orderItem (Shopper\Core\Models\OrderItem).
Lifecycle Flow
OrderCreated
│
├── OrderPaid
│ │
│ ├── OrderShipped ──> OrderCompleted
│ │
│ └── OrderCancelled
│
├── OrderCancelled
│
├── OrderArchived
│
└── OrderDeletedHow They Are Dispatched
OrderCreated and OrderDeleted are dispatched by Shopper\Core\Observers\OrderObserver, registered on the model set in config('shopper.models.order'). They fire on every Eloquent insert and delete, whether the operation comes from the admin panel, the cart checkout or your own code. OrderDeleted fires from the deleting hook, before the row is soft-deleted or removed. OrderItemCreated works the same way through OrderItemObserver, once per order item. Mass updates and deletes run through the query builder skip model events.
use Shopper\Core\Models\Order;
$order = Order::query()->create([
'number' => generate_number(),
'price_amount' => 12900,
'currency_code' => shopper_currency(),
'customer_id' => $customer->id,
]);Status-related events (OrderPaid, OrderCompleted, OrderCancelled, OrderArchived) are dispatched from the admin panel when an administrator changes the order status with the Mark as paid, Mark complete, Cancel Order or Archive action of the order detail page. Updating status or payment_status in your own code dispatches nothing: dispatch the event yourself, for example event(new OrderPaid($order)). Two built-in paths also change these statuses without an event: capturing an authorized payment sets payment_status to paid without OrderPaid, and delivering the last package sets status to completed without OrderCompleted.
OrderShipped is dispatched by SyncOrderShippingStatusAction when the order's shipping_status transitions to Shipped, which means every item has the shipped fulfillment status. The action runs each time a shipment is recorded as picked up, delivered or returned, so you don't dispatch it manually.
Dispatch After Commit
All order events implement Laravel's ShouldDispatchAfterCommit contract. When one is dispatched inside a database transaction, Laravel holds it until the transaction commits and drops it if the transaction rolls back. Outside a transaction, it is dispatched at once. The checkout creates the order and its items in the same transaction, so an OrderCreated listener finds the items.
The contract does not queue anything: a listener runs during the request unless it implements Illuminate\Contracts\Queue\ShouldQueue.
| Event | After commit |
|---|---|
OrderCreated | Yes |
OrderItemCreated | Yes |
OrderPaid | Yes |
OrderCompleted | Yes |
OrderShipped | Yes |
OrderCancelled | Yes |
OrderArchived | Yes |
OrderDeleted | Yes |
OrderNoteAdded | Yes |
Shipment Events
Shipment events track the creation and delivery of individual packages within an order. A single order can have multiple shipments.
Available Events
| Event | Payload | Trigger |
|---|---|---|
OrderShipmentCreated | Order $order, OrderShipping $shipment | Admin creates a shipping label, which creates a new shipment |
OrderShipmentDelivered | Order $order, OrderShipping $shipment | A shipment is marked as delivered with MarkShipmentDeliveredAction |
Both shipment events carry two properties: the order and the specific shipment. This is useful when an order has multiple packages and you need to know which one was created or delivered. Both implement ShouldDispatchAfterCommit.
OrderShipmentDelivered comes from MarkShipmentDeliveredAction, which the Mark as delivered action of the shipments list calls. Recording a Delivered status with Add event in the shipment panel updates the shipment and its items but does not dispatch it.
use Shopper\Core\Events\Orders\OrderShipmentDelivered;
class NotifyCustomerOfDelivery
{
public function handle(OrderShipmentDelivered $event): void
{
$order = $event->order;
$shipment = $event->shipment;
$trackingNumber = $shipment->tracking_number;
$deliveredItems = $shipment->items;
}
}Shipment vs Order Events
Shipment events fire at the package level, order events fire at the order level:
| Scenario | Events fired |
|---|---|
| Label created for the first package (2 of 3 items) | OrderShipmentCreated |
| Label created for the second package (last item) | OrderShipmentCreated |
| Last package picked up, every item now shipped | OrderShipped |
| First package delivered | OrderShipmentDelivered |
| Last package delivered | OrderShipmentDelivered, and the order status becomes completed if it was processing (no OrderCompleted) |
OrderShipped needs every item shipped at the same time. If a package is delivered before the last one is picked up, the order goes from partially shipped to partially delivered and OrderShipped is not dispatched.
Product Events
Product events are dispatched when products are created, updated, or deleted through the admin panel.
Available Events
| Event | Payload | Trigger |
|---|---|---|
ProductCreated | Product $product | Product is created via admin |
ProductUpdated | Product $product | Product Overview form is saved via admin |
ProductDeleted | Product $product | Product is deleted via admin, dispatched just before the delete |
These events come from the admin actions, not from a model observer: Product::query()->create() or $product->update() in your own code dispatches nothing. Saving the other tabs of the product page (media, files, inventory, shipping, SEO) does not dispatch ProductUpdated.
use Shopper\Core\Events\Products\ProductCreated;
class SyncProductToCatalog
{
public function handle(ProductCreated $event): void
{
$product = $event->product;
ExternalCatalog::push($product);
}
}All product events implement ShouldDispatchAfterCommit: inside a database transaction, they wait for the commit. Listeners run during the request unless they implement ShouldQueue.
Example: Order Notification System
Here's how you might use Shopper events to build a notification flow for your store. Each listener handles a single responsibility.
Register your listeners:
use Shopper\Core\Events\Orders\OrderCreated;
use Shopper\Core\Events\Orders\OrderPaid;
use Shopper\Core\Events\Orders\OrderShipped;
use Shopper\Core\Events\Orders\OrderShipmentDelivered;
protected $listen = [
OrderCreated::class => [
SendOrderConfirmationToCustomer::class,
NotifyWarehouseTeam::class,
],
OrderPaid::class => [
GenerateInvoice::class,
SyncPaymentToAccounting::class,
],
OrderShipped::class => [
SendShippingConfirmation::class,
],
OrderShipmentDelivered::class => [
SendDeliveryConfirmation::class,
RequestProductReview::class,
],
];A listener that sends a shipping confirmation:
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;
use Shopper\Core\Events\Orders\OrderShipped;
class SendShippingConfirmation implements ShouldQueue
{
public function handle(OrderShipped $event): void
{
$order = $event->order;
$order->load('customer', 'shippings.carrier');
if ($order->customer === null) {
return;
}
Mail::to($order->customer->email)
->send(new OrderShippedMail($order));
}
}Cart Events
Cart events are dispatched when a cart reaches a key state during the checkout process.
Available Events
| Event | Payload | Trigger |
|---|---|---|
CartCompleted | Cart $cart, Order $order | CreateOrderFromCartAction converts the cart to an order |
CouponApplied | Cart $cart, string $code | CartManager::applyCoupon() stores a code that matches an existing discount on the cart |
CouponRemoved | Cart $cart | CartManager::removeCoupon() clears the coupon code from the cart |
CouponRemoved does not carry the removed code: the cart's coupon_code is already null when it fires.
Cart events do not implement ShouldDispatchAfterCommit. CartCompleted is dispatched inside the checkout transaction, before the commit: a listener that runs during the request runs inside that transaction, and an exception it throws rolls the order back. A queued listener should implement Illuminate\Contracts\Queue\ShouldQueueAfterCommit so it never runs before the order is saved.
Cart events are in the Shopper\Cart\Events namespace:
use Shopper\Cart\Events\CartCompleted;
use Shopper\Cart\Events\CouponApplied;
use Shopper\Cart\Events\CouponRemoved;Example: Sending a Cart Recovery Email on Coupon Removal
use Illuminate\Support\Facades\Mail;
use Shopper\Cart\Events\CouponRemoved;
class OfferAlternativeCoupon
{
public function handle(CouponRemoved $event): void
{
$cart = $event->cart;
$customer = $cart->customer;
if ($customer) {
Mail::to($customer->email)->send(new AlternativeDiscountMail($cart));
}
}
}All Events Reference
| Namespace | Event | Payload | After commit |
|---|---|---|---|
Events\Orders | OrderCreated | Order $order | Yes |
Events\Orders | OrderItemCreated | OrderItem $orderItem | Yes |
Events\Orders | OrderPaid | Order $order | Yes |
Events\Orders | OrderCompleted | Order $order | Yes |
Events\Orders | OrderShipped | Order $order | Yes |
Events\Orders | OrderCancelled | Order $order | Yes |
Events\Orders | OrderArchived | Order $order | Yes |
Events\Orders | OrderDeleted | Order $order | Yes |
Events\Orders | OrderNoteAdded | Order $order | Yes |
Events\Orders | OrderShipmentCreated | Order $order, OrderShipping $shipment | Yes |
Events\Orders | OrderShipmentDelivered | Order $order, OrderShipping $shipment | Yes |
Events\Products | ProductCreated | Product $product | Yes |
Events\Products | ProductUpdated | Product $product | Yes |
Events\Products | ProductDeleted | Product $product | Yes |
Cart\Events | CartCompleted | Cart $cart, Order $order | No |
Cart\Events | CouponApplied | Cart $cart, string $code | No |
Cart\Events | CouponRemoved | Cart $cart | No |
Last updated on
Edit on GitHub