Skip to content

Events

The events Shopper dispatches for orders, payments, shipments, products, customers and carts, when each one fires, and how to listen to them.

Shopper dispatches Laravel events when an order is placed, paid, shipped or cancelled, when a payment fails, when a product changes and when a customer signs up. Your application listens to them to send emails, sync an ERP or a warehouse, or feed analytics, without changing Shopper's code.

Each package keeps its events in its own namespace:

NamespacePackageEvents
Shopper\Core\Events\Ordersshopper/coreOrders, order items and shipments
Shopper\Core\Events\Productsshopper/coreProducts and product imports
Shopper\Core\Events\Customersshopper/coreCustomer sign-ups
Shopper\Core\Events\Paymentsshopper/corePayments received without an order
Shopper\Payment\Eventsshopper/paymentFailed payments
Shopper\Cart\Eventsshopper/cartCheckout, coupons and cart prices
Shopper\Eventsshopper/frameworkAdmin panel

Listening to Events

Laravel 12 and 13 discover the listeners stored in app/Listeners: a class whose handle method type-hints a Shopper event is registered for that event, with no other step.

app/Listeners/RecordSaleInAccounting.php
namespace App\Listeners;

use App\Services\Accounting;
use Shopper\Core\Events\Orders\OrderPaid;

class RecordSaleInAccounting
{
    public function __construct(private Accounting $accounting) {}

    public function handle(OrderPaid $event): void
    {
        $this->accounting->recordSale($event->order);
    }
}

Every event exposes its payload as public properties, such as $event->order above. Order, product and cart payloads are typed with the model contracts, so a listener receives your own model when you replace one: orders and products in config/shopper/models.php, as the Models page explains, and carts in the models key of config/shopper/cart.php.

A listener stored in another directory is registered in the boot method of a service provider:

app/Providers/AppServiceProvider.php
use App\Warehouse\CancelPickingList;
use Illuminate\Support\Facades\Event;
use Shopper\Core\Events\Orders\OrderCancelled;

public function boot(): void
{
    Event::listen(OrderCancelled::class, CancelPickingList::class);
}

Register each listener one way only: a listener in app/Listeners that is also passed to Event::listen() runs twice. To see every listener attached to a Shopper event, Shopper's own included, run:

php artisan event:list --event=Shopper

Dispatched After Commit

Most Shopper events implement Laravel's ShouldDispatchAfterCommit contract. When such an event is dispatched inside a database transaction, Laravel holds it until the transaction commits, and drops it if the transaction rolls back. A listener therefore never sees a half-written order: OrderCreated is dispatched when the order row is inserted, yet the checkout writes the items, the addresses and the promotions in the same transaction, and the listener finds all of them. Outside a transaction, the event is dispatched at once. The reference table shows which events wait for the commit.

Waiting for the commit does not put a listener on the queue. Listeners still run during the request that dispatched the event, unless you queue them.

Queueing Listeners

A listener that calls an external service or sends an email should not slow down the checkout or the admin panel. Implement ShouldQueue and Laravel pushes the listener to the queue instead of running it during the request:

app/Listeners/RecordSaleInAccounting.php
namespace App\Listeners;

use App\Services\Accounting;
use Illuminate\Contracts\Queue\ShouldQueue;
use Shopper\Core\Events\Orders\OrderPaid;

class RecordSaleInAccounting implements ShouldQueue
{
    public $queue = 'accounting';

    public function __construct(private Accounting $accounting) {}

    public function handle(OrderPaid $event): void
    {
        $this->accounting->recordSale($event->order);
    }
}

The $queue property sends the job to a named queue. Without it, the job goes to the default queue. The queue worker must listen to every queue your listeners use, as described in Installation.

Most Shopper events use Laravel's SerializesModels trait: the queued job stores the IDs of the models and loads them again when it runs. The listener reads the order as it is when the job runs, which can differ from the order at dispatch time.

Order Events

Order events follow an order from checkout to completion, cancellation or archiving. They live in the Shopper\Core\Events\Orders namespace.

Available Events

The order events carry the order as public Order $order, typed with the Shopper\Core\Models\Contracts\Order contract. OrderItemCreated carries public OrderItem $orderItem, an instance of Shopper\Core\Models\OrderItem.

EventPayloadDispatched when
OrderCreatedOrder $orderAn order row is inserted, at checkout or from your own code
OrderItemCreatedOrderItem $orderItemAn order item row is inserted
OrderPaidOrder $orderThe payment status becomes Paid, see Payment Events
OrderShippedOrder $orderThe shipping status of the order becomes Shipped, see Shipment Events
OrderCompletedOrder $orderThe order moves to Completed
OrderCancelledOrder $orderThe order moves to Cancelled
OrderArchivedOrder $orderThe order is archived from the admin panel
OrderNoteAddedOrder $orderA private note is saved on the order in the admin panel
OrderDeletedOrder $orderAn order is deleted, soft or forced

OrderCreated, OrderItemCreated and OrderDeleted come from model observers, so they fire wherever the row is created or deleted. An order inserted by your own code outside a transaction dispatches OrderCreated at once, before you add its items. The admin panel never deletes an order: OrderDeleted only fires when your code deletes one.

Order Lifecycle

An order carries three statuses: status for the order itself, payment_status for its payment and shipping_status for its packages. The order status follows the Shopper\Core\Enum\OrderStatus state machine:

StatusCan move to
NewProcessing, Completed, Cancelled, Archived
ProcessingCompleted, Cancelled, Archived
CompletedCancelled, Archived
CancelledArchived
ArchivedNone

$order->transitionTo() refuses any other move with a Shopper\Core\Exceptions\InvalidOrderStatusTransitionException. It dispatches no event: the code that moves the order dispatches the matching event after the transition. Shopper moves orders in these places:

MoveTriggered byEvent
Created as NewThe checkout turns a cart into an orderOrderCreated
New to ProcessingStart processing or Mark as paid in the admin panel, or the carrier picking up the first packageNone
Processing to CompletedMark complete in the admin panel, offered once the order is paid, or automatically once the order is paid and every item is deliveredOrderCompleted
To CancelledCancel Order in the admin panel, a cancellation reported by the payment provider on an unpaid order, or the hourly shopper:orders:reclaim command for orders left unpaidOrderCancelled
To ArchivedArchive in the admin panel, offered for orders neither paid nor completedOrderArchived

The automatic completion runs in two places: when the last package of a paid order is delivered, and when an order whose items are all delivered gets paid, through the OrderPaid listener Shopper registers. An item whose package came back is never counted as delivered, so an order with a returned package is not completed automatically. The delay before shopper:orders:reclaim cancels an unpaid order is set by reclaim_pending_after_hours in config/shopper/orders.php, described on the Configuration page.

When your own code moves an order, dispatch the matching event after the transition so that your listeners and the webhooks see the change:

use Shopper\Core\Enum\OrderStatus;
use Shopper\Core\Events\Orders\OrderCompleted;

$order->transitionTo(OrderStatus::Completed);

OrderCompleted::dispatch($order);

Payment Events

The payment status follows its own state machine, Shopper\Core\Enum\PaymentStatus: Pending moves to Authorized, Paid or Voided; Authorized to Paid or Voided; Paid to Partially refunded or Refunded; Partially refunded to Partially refunded or Refunded. Only the move to Paid dispatches an event. Amounts in payment events are in cents.

EventNamespacePayloadDispatched when
OrderPaidShopper\Core\Events\OrdersOrder $orderThe payment status becomes Paid
PaymentFailedShopper\Payment\EventsOrder $order, TransactionType $type, ?string $reasonThe provider declines an authorization, a capture or a refund
PaymentOrphanedShopper\Core\Events\Paymentsstring $driver, string $reference, ?int $amount, ?string $cartIdA payment authorized or captured by the provider still has no order
OrphanedPaymentRefundedShopper\Core\Events\Paymentsstring $driver, string $reference, ?int $amountAn orphaned payment is refunded

OrderPaid is dispatched by $order->transitionPaymentTo(PaymentStatus::Paid), whatever moved the payment: Mark as paid in the admin panel for offline payments such as cash on delivery, Capture payment in the admin panel for an authorized payment, or the capture event of the payment provider, applied at checkout, from the provider's webhook or by the shopper:payments:reconcile command.

PaymentFailed carries $type, a Shopper\Payment\Enum\TransactionType case (Authorize, Capture or Refund), and $reason, the message returned by the provider. A payment failure reported by the provider's webhook only dispatches the event while the payment is still pending: the order keeps its reserved stock so that the customer can try again. A refund the provider reports as failed dispatches it with the Refund type whatever the payment status, as described in Pending Refunds.

Orphaned Payments

A customer can pay and lose the connection before the checkout creates the order. Every 15 minutes, the scheduled shopper:payments:reconcile command looks for provider authorizations and captures that still have no order after reconciliation.orphan_after_minutes in config/shopper/payment.php (30 by default, set with PAYMENT_ORPHAN_AFTER_MINUTES), and dispatches PaymentOrphaned for each one the provider has not since reported as refunded or canceled. A refund the provider has reported as failed does not count. Listeners run during the command and answer through three methods of the event:

MethodMeaning
recognize()The payment belongs to one of the store's carts
resolve()The listener created the order for this payment
defer()The payment is checked again on the next run

Shopper's cart package recognizes a payment whose reference matches a cart. With the Store API installed, a second listener completes that cart and calls resolve(), or defer() when the cart is locked or the provider does not answer. A payment recognized but not resolved is reported to your exception handler, then refunded when config('shopper.payment.reconciliation.orphans') is refund (PAYMENT_ORPHANS, alert by default). A successful refund dispatches OrphanedPaymentRefunded, with $amount set to null. The provider's refund webhook also dispatches it for a payment without an order, with the refunded amount when the provider sends one. A refund the provider reports as failed for a payment without an order is reported to your exception handler. A storefront that completes its checkout without the Store API can listen to PaymentOrphaned and complete the cart the same way.

Shipment Events

An order ships in one or more packages, each an OrderShipping model with its own status. A package is created from the order page of the admin panel. Its status then changes when an administrator records a tracking event or marks it delivered, or when the carrier reports it, through its webhook or the shopper:shipments:sync-tracking command. The Fulfillment page describes the shipment statuses.

Available Events

Shipment events live in Shopper\Core\Events\Orders with the order events. They carry the order and the package, an instance of Shopper\Core\Models\OrderShipping:

EventPayloadDispatched when
OrderShipmentCreatedOrder $order, OrderShipping $shipmentA package is created, with the status Pending
OrderShipmentDeliveredOrder $order, OrderShipping $shipmentThe package reaches Delivered
OrderShipmentDeliveryFailedOrder $order, OrderShipping $shipmentThe package reaches Delivery failed
OrderShipmentReturnedOrder $order, OrderShipping $shipmentThe package reaches Returned
OrderShipmentEventRecordedOrder $order, OrderShipping $shipment, OrderShippingEvent $event, bool $statusChangedA tracking event is recorded on the package
OrderShippedOrder $orderThe shipping status of the order becomes Shipped

OrderShipmentEventRecorded fires each time a tracking event is recorded on an existing package, after the event of the status it reached. The Pending event written when the package is created only dispatches OrderShipmentCreated. $event is the Shopper\Core\Models\OrderShippingEvent row. $statusChanged is false when a carrier scan is logged without changing the package status, such as a scan older than the current status. A carrier event already recorded under the same external ID is ignored and dispatches nothing.

app/Listeners/PushTrackingToCustomerApp.php
namespace App\Listeners;

use App\Services\PushNotifications;
use Shopper\Core\Events\Orders\OrderShipmentEventRecorded;

class PushTrackingToCustomerApp
{
    public function __construct(private PushNotifications $push) {}

    public function handle(OrderShipmentEventRecorded $event): void
    {
        if (! $event->statusChanged) {
            return;
        }

        $this->push->send($event->order->customer, $event->shipment->tracking_number, $event->event->status);
    }
}

Shipment vs Order Events

Shipment events fire per package, order events per order. A status recorded on a package also updates its items and the order:

  • The first time a package reaches Picked up or a later status other than Returned, its items become Shipped, a New order moves to Processing, and the shipping status of the order is computed again. OrderShipped fires when every item of the order is shipped and none is delivered or returned yet.
  • When a package is delivered, its items become Delivered, and the order is completed if it is paid, in Processing, and every item is delivered.
  • When a package is returned, its items become Cancelled and the shipping status of the order is computed again: Returned when every item came back, Partially returned when the other items are all shipped or delivered.
  • Delivery failed changes nothing else.

For a paid order of three items sent in two packages, the events arrive in this order:

StepEvents, in dispatch order
Package A is created with two itemsOrderShipmentCreated
The carrier picks up package AOrderShipmentEventRecorded
Package B is created with the last itemOrderShipmentCreated
The carrier picks up package B while A is in transitOrderShipped, OrderShipmentEventRecorded
The first delivery attempt of package A failsOrderShipmentDeliveryFailed, OrderShipmentEventRecorded
Package A is deliveredOrderShipmentDelivered, OrderShipmentEventRecorded
Package B is deliveredOrderCompleted, OrderShipmentDelivered, OrderShipmentEventRecorded

A package that comes back to the store dispatches OrderShipmentReturned, then OrderShipmentEventRecorded.

OrderShipped never fires when a package is delivered before the last package is picked up: the shipping status of the order goes from Partially delivered to Delivered without passing through Shipped. To follow every package, listen to the shipment events.

Product Events

Product events live in Shopper\Core\Events\Products. The product events carry public Product $product, typed with the Shopper\Core\Models\Contracts\Product contract. The admin panel and the CSV import dispatch them, no model observer does: Product::create() in your own code or in a seeder dispatches nothing.

EventPayloadDispatched when
ProductCreatedProduct $productA product is created in the admin panel, or a CSV import creates a new product
ProductUpdatedProduct $productThe main product form is saved in the admin panel
ProductDeletedProduct $productA product is deleted from the admin panel, just before the deletion
ProductImportCompletedProductImport $importA CSV import finishes

ProductUpdated only fires from the main form of the product page: name, description, visibility, publication date, channels, brand, categories, collections and tags. Saving the pricing, inventory, media, files, shipping, SEO, attributes or variants of a product, or updating an existing product through a CSV import, dispatches no event.

Products are soft deleted, so a queued listener of ProductDeleted still loads the product it receives.

ProductImportCompleted carries the Shopper\Core\Models\ProductImport record. Its status is Completed or CompletedWithErrors (Shopper\Core\Enum\ImportStatus), next to the total_products, imported_count, failed_count and errors columns. An import that fails before its rows are read ends with the status Failed and dispatches no event. The Import page covers the CSV format.

Customer Events

Shopper\Core\Events\Customers\CustomerRegistered carries public Authenticatable $customer, an instance of your user model. It fires when a customer is created in the admin panel, or signs up through POST /store/auth/register, the registration endpoint of the Store API. A sign-up handled by your own code dispatches no Shopper event.

The Store API also dispatches two Laravel events: Illuminate\Auth\Events\Lockout when a login is refused after too many failed attempts, and Illuminate\Auth\Events\PasswordReset when a customer resets their password.

Cart and Discount Events

Cart events live in Shopper\Cart\Events and carry the cart as public Cart $cart, typed with the Shopper\Cart\Models\Contracts\Cart contract. Shopper dispatches no event when a discount or a campaign is created, changed or used up: the coupon events come from the cart.

EventPayloadDispatched when
CartCompletedCart $cart, Order $orderThe checkout turns the cart into an order
CouponAppliedCart $cart, string $codeA coupon code is applied to the cart
CouponRemovedCart $cartCoupon codes are removed from the cart
CartLinesRepricedCart $cart, Collection $changesThe unit price of one or more lines changes

CartCompleted is dispatched once the order, its items and the cart are committed, after OrderCreated and OrderItemCreated.

CouponRemoved does not say which code left the cart. It fires when the customer removes a code through DELETE /store/carts/{cartId}/promotion, which removes every code when the request names none, and when Shopper drops a code that no longer applies after the currency or the zone of the cart changes, or when a signed-in customer takes over a guest cart. It also fires when the code to remove was not on the cart.

CartLinesRepriced fires when Shopper prices a cart again and at least one unit price changed: when the zone or the channel of the cart changes, when a signed-in customer takes over or merges a guest cart, before a payment session is created, and when the checkout is refused because a unit price went up. Each item of $changes is an array with line, the Shopper\Cart\Models\CartLine, and from and to, the unit price before and after, in cents.

Admin Panel Events

The shopper/framework package dispatches three events from the admin panel:

EventPayloadDispatched when
Shopper\Events\LoadShopperNoneOn every request to the admin panel, Livewire requests included
Shopper\Events\TwoFactor\TwoFactorAuthenticationEnabled$userAn admin user turns on two-factor authentication from their profile
Shopper\Events\TwoFactor\TwoFactorAuthenticationDisabled$userNever dispatched

Shopper::serving() attaches a closure to LoadShopper, to run code only when the admin panel is serving a request, and Shopper::isServing() tells whether the current request belongs to the admin panel. Both come from the Shopper\Facades\Shopper facade.

TwoFactorAuthenticationDisabled exists, but Shopper does not dispatch it when a user turns two-factor authentication off, so a listener on it never runs. The Two-Factor Authentication page covers the feature.

The sidebar of the admin panel is built through its own Shopper\Sidebar\SidebarBuilder event. The Navigation page shows how to add menu groups and items with it.

Listeners Shopper Registers

Shopper listens to some of its own events. Check this list before writing a listener, so that yours does not repeat their work:

EventListenerWhat it doesRuns
OrderCreatedShopper\Listeners\EnsureCustomerRoleGives the order's customer the role set in config('shopper.admin.roles.user')During the request
OrderPaidShopper\Core\Listeners\Orders\CompleteFulfilledOrderListenerCompletes the order when every item is already deliveredDuring the request
OrderCancelledShopper\Core\Listeners\Orders\RestoreOrderStockListenerPuts the stock reserved by the order back on saleDefault queue
OrderCancelledShopper\Core\Listeners\Orders\ReleaseCampaignBudgetListenerGives the discount budget spent by the order back to its campaignDefault queue
PaymentOrphanedShopper\Cart\Listeners\RecognizeOrphanedPaymentRecognizes a payment that matches a cartDuring the command
PaymentOrphanedShopper\Api\Listeners\CompleteOrphanedCartCompletes the cart the payment belongs to, with the Store API installedDuring the command
OrphanedPaymentRefundedShopper\Cart\Listeners\ForgetRefundedPaymentSessionClears the refunded payment session from its cartDuring the request or the command

When notifications.database.enabled is true in config/shopper/admin.php (false by default), the admin panel also notifies its administrators under the bell of the top bar on OrderCreated, OrderPaid, PaymentFailed and ProductImportCompleted. These four listeners run on a queue named notifications, so the queue worker must listen to it. The Notifications page describes them.

Example: Order Notification System

A store emails the customer when the order is placed, then again when each package arrives. Two queued listeners in app/Listeners cover it, each with a mailable created by php artisan make:mail:

app/Listeners/SendOrderConfirmation.php
namespace App\Listeners;

use App\Mail\OrderConfirmation;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;
use Shopper\Core\Events\Orders\OrderCreated;

class SendOrderConfirmation implements ShouldQueue
{
    public function handle(OrderCreated $event): void
    {
        Mail::to($event->order->email)->send(new OrderConfirmation($event->order));
    }
}

The Store API checkout always stores the customer's email on the order, for guests and signed-in customers alike. OrderCreated fires as soon as the order exists, before a card payment is captured: to confirm paid orders only, listen to OrderPaid instead.

app/Listeners/SendDeliveryConfirmation.php
namespace App\Listeners;

use App\Mail\PackageDelivered;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Support\Facades\Mail;
use Shopper\Core\Events\Orders\OrderShipmentDelivered;

class SendDeliveryConfirmation implements ShouldQueue
{
    public function handle(OrderShipmentDelivered $event): void
    {
        $event->shipment->load('items');

        Mail::to($event->order->email)->send(new PackageDelivered($event->order, $event->shipment));
    }
}

OrderShipmentDelivered sends one email per package, with the items it carried. OrderCompleted fires once per order and suits a single thank-you email, sent when the last package is delivered on a paid order.

Webhooks

Fourteen of these events can also reach external systems as signed HTTP requests. A webhook subscription picks events by their public name, given in the Webhook column of the reference table, such as order.paid or shipment.delivered. The other events are never sent as webhooks. The map from event class to name lives in the events key of config/shopper/webhooks.php, and the Shopper\Core\Webhooks\Facades\Webhooks facade registers your own events with Webhooks::register(). The Webhooks page covers subscriptions, payloads, signatures and retries.

All Events Reference

The After commit column marks the events that implement ShouldDispatchAfterCommit.

EventNamespaceAfter commitWebhook
OrderCreatedShopper\Core\Events\OrdersYesorder.created
OrderItemCreatedShopper\Core\Events\OrdersYesNone
OrderPaidShopper\Core\Events\OrdersYesorder.paid
OrderShippedShopper\Core\Events\OrdersYesorder.shipped
OrderCompletedShopper\Core\Events\OrdersYesorder.completed
OrderCancelledShopper\Core\Events\OrdersYesorder.cancelled
OrderArchivedShopper\Core\Events\OrdersYesNone
OrderNoteAddedShopper\Core\Events\OrdersYesNone
OrderDeletedShopper\Core\Events\OrdersYesNone
OrderShipmentCreatedShopper\Core\Events\OrdersYesshipment.created
OrderShipmentDeliveredShopper\Core\Events\OrdersYesshipment.delivered
OrderShipmentDeliveryFailedShopper\Core\Events\OrdersYesshipment.delivery_failed
OrderShipmentReturnedShopper\Core\Events\OrdersYesshipment.returned
OrderShipmentEventRecordedShopper\Core\Events\OrdersYesNone
PaymentFailedShopper\Payment\EventsYesNone
PaymentOrphanedShopper\Core\Events\PaymentsNoNone
OrphanedPaymentRefundedShopper\Core\Events\PaymentsNoNone
ProductCreatedShopper\Core\Events\ProductsYesproduct.created
ProductUpdatedShopper\Core\Events\ProductsYesproduct.updated
ProductDeletedShopper\Core\Events\ProductsYesproduct.deleted
ProductImportCompletedShopper\Core\Events\ProductsNoNone
CustomerRegisteredShopper\Core\Events\CustomersYescustomer.registered
CartCompletedShopper\Cart\EventsYescart.completed
CouponAppliedShopper\Cart\EventsNoNone
CouponRemovedShopper\Cart\EventsNoNone
CartLinesRepricedShopper\Cart\EventsNoNone
LoadShopperShopper\EventsNoNone
TwoFactorAuthenticationEnabledShopper\Events\TwoFactorNoNone
TwoFactorAuthenticationDisabledShopper\Events\TwoFactorNoNone

Last updated on

Edit on GitHub