PHP Events Reference

Craft CMS exposes core events you can hook into. YuiCraftPlugin adds additional events for storefront behavior, checkout flow, admin registration points, and automation.

The following events are available.

Event	Description
EVENT_AFTER_CART_VIEW	Triggered after a customer views the cart
EVENT_AFTER_CART_ITEMS	Triggered after cart items are prepared
EVENT_AFTER_ADD_TO_CART	Triggered after an item is added to the cart
EVENT_AFTER_REMOVE_FROM_CART	Triggered after an item is removed from the cart
EVENT_MODIFY_CART_TOTALS	Triggered after cart totals are prepared
EVENT_AFTER_SHIPPING_METHOD_LOAD	Triggered after the shipping methods are loaded
EVENT_BEFORE_PAYMENT_METHOD_LOAD	Triggered before the payment methods are loaded
EVENT_AFTER_PAYMENT_METHOD_LOAD	Triggered after the payment methods are loaded
EVENT_AFTER_QUOTE_QUICK_SAVE	Triggered after the quote is quick-saved
EVENT_AFTER_QUOTE_ITEM_UPDATE	Triggered after quote items are updated
EVENT_AFTER_QUOTE_METHOD_UPDATE	Triggered after quote shipping/payment methods are updated
EVENT_AFTER_QUOTE_CALCULATE_DISCOUNTS	Triggered after the quote discounts are calculated
EVENT_AFTER_BEGIN_CHECKOUT	Triggered after checkout begins
EVENT_AFTER_REGISTER_SHIPPING_METHOD_INFO	Triggered after shipping method info is registered
EVENT_AFTER_REGISTER_PAYMENT_METHOD_INFO	Triggered after payment method info is registered
EVENT_AFTER_PURCHASE_SUCCESS	Triggered after a successful purchase
EVENT_AFTER_PURCHASE_FAIL	Triggered after a failed purchase
EVENT_AFTER_CUSTOMER_LOGIN	Triggered after a customer logs in
EVENT_AFTER_CUSTOMER_SIGN_UP	Triggered after a customer signs up
EVENT_REGISTER_CHECKOUT_BLOCK_TYPES	Triggered when registering block types for the checkout designer
EVENT_REGISTER_CART_BLOCK_TYPES	Triggered when registering block types for the cart and checkout result designers
EVENT_REGISTER_MODULES	Triggered when dashboard modules are registered
EVENT_REGISTER_EMAIL_STYLES	Triggered when email styles are registered
EVENT_BEFORE_GIFT_CARD_GENERATED	Triggered before a gift card PDF is generated
EVENT_AFTER_GIFT_CARD_GENERATED	Triggered after a gift card PDF is generated
EVENT_AFTER_GIFT_CARD_CODES_GENERATED	Triggered after gift card codes are generated
EVENT_AFTER_ORDER_STATUS_CHANGE	Triggered after an order status changes
EVENT_AFTER_ORDER_METHOD_UPDATE	Triggered after order shipping/payment methods are updated
EVENT_AFTER_ORDER_COLLECT_ATTACHMENTS	Triggered after order attachments are collected
EVENT_AFTER_PRODUCT_VIEW	Triggered after a product is viewed
EVENT_AFTER_SEARCH	Triggered after a search is performed
EVENT_REGISTER_THEMES	Triggered when themes are registered
EVENT_REGISTER_TRIGGER_DEFINITIONS	Triggered when flow trigger definitions are registered
EVENT_REGISTER_ACTION_DEFINITIONS	Triggered when flow action definitions are registered
EVENT_REGISTER_CONDITION_DEFINITIONS	Triggered when flow condition definitions are registered
EVENT_REGISTER_LOGIC_DEFINITIONS	Triggered when flow logic definitions are registered
EVENT_MODIFY_TOTAL_LABELS	Triggered when cart and checkout total labels are resolved

EVENT_AFTER_CART_VIEW

Triggered after a customer views the cart.

use yii\base\Event;
use yui\craft\events\CartViewEvent;
use yui\craft\services\CartService;

Event::on(CartService::class, CartService::EVENT_AFTER_CART_VIEW, function(CartViewEvent $event) {
    // $event->currency, $event->value, $event->items
});

EVENT_AFTER_CART_ITEMS

Triggered after cart items are prepared.

use yii\base\Event;
use yui\craft\events\CartItemsEvent;
use yui\craft\services\CartService;

Event::on(CartService::class, CartService::EVENT_AFTER_CART_ITEMS, function(CartItemsEvent $event) {
    // $event->items
});

EVENT_AFTER_ADD_TO_CART

Triggered after an item is added to the cart.

use yii\base\Event;
use yui\craft\events\CartAddToEvent;
use yui\craft\services\CartService;

Event::on(CartService::class, CartService::EVENT_AFTER_ADD_TO_CART, function(CartAddToEvent $event) {
    // $event->currency, $event->value, $event->items
});

EVENT_AFTER_REMOVE_FROM_CART

Triggered after an item is removed from the cart.

use yii\base\Event;
use yui\craft\events\CartRemoveItemEvent;
use yui\craft\services\CartService;

Event::on(CartService::class, CartService::EVENT_AFTER_REMOVE_FROM_CART, function(CartRemoveItemEvent $event) {
    // $event->currency, $event->value, $event->items
});

EVENT_MODIFY_CART_TOTALS

Triggered after cart totals are prepared. Handlers can insert custom totals before or after existing keys.

use yii\base\Event;
use yui\craft\events\CartTotalsEvent;
use yui\craft\services\CartService;

Event::on(CartService::class, CartService::EVENT_MODIFY_CART_TOTALS, function(CartTotalsEvent $event) {
    $event->addTotalBefore('grand_total', 'custom_fee', [
        'label' => 'Custom Fee',
        'value' => 12.5,
        'currency' => 'EUR',
    ]);
});

EVENT_AFTER_SHIPPING_METHOD_LOAD

Triggered after the shipping methods are loaded.

use yii\base\Event;
use yui\craft\events\CheckoutAfterShippingMethodLoadEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_SHIPPING_METHOD_LOAD, function(CheckoutAfterShippingMethodLoadEvent $event) {
    // $event->quote, $event->methods
});

EVENT_BEFORE_PAYMENT_METHOD_LOAD

Triggered before the payment methods are loaded.

use yii\base\Event;
use yui\craft\events\CheckoutBeforePaymentMethodLoadEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_BEFORE_PAYMENT_METHOD_LOAD, function(CheckoutBeforePaymentMethodLoadEvent $event) {
    // $event->quote, $event->methods
});

EVENT_AFTER_PAYMENT_METHOD_LOAD

Triggered after the payment methods are loaded.

use yii\base\Event;
use yui\craft\events\CheckoutAfterPaymentMethodLoadEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_PAYMENT_METHOD_LOAD, function(CheckoutAfterPaymentMethodLoadEvent $event) {
    // $event->quote, $event->methods
});

EVENT_AFTER_QUOTE_QUICK_SAVE

Triggered after the quote is quick-saved.

use yii\base\Event;
use yui\craft\events\QuoteQuickSaveEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_QUOTE_QUICK_SAVE, function(QuoteQuickSaveEvent $event) {
    // $event->request, $event->cartId
});

EVENT_AFTER_QUOTE_ITEM_UPDATE

Triggered after quote items are updated, including deletion.

use yii\base\Event;
use yui\craft\events\QuoteItemUpdateEvent;
use yui\craft\services\sales\QuoteService;

Event::on(QuoteService::class, QuoteService::EVENT_AFTER_QUOTE_ITEM_UPDATE, function(QuoteItemUpdateEvent $event) {
    // $event->quote
});

EVENT_AFTER_QUOTE_METHOD_UPDATE

Triggered after quote shipping/payment methods are updated.

use yii\base\Event;
use yui\craft\events\QuoteMethodUpdateEvent;
use yui\craft\services\sales\QuoteService;

Event::on(QuoteService::class, QuoteService::EVENT_AFTER_QUOTE_METHOD_UPDATE, function(QuoteMethodUpdateEvent $event) {
    // $event->quote
});

EVENT_AFTER_QUOTE_CALCULATE_DISCOUNTS

Triggered after the quote discounts are calculated.

use yii\base\Event;
use yui\craft\events\QuoteCalculateDiscountsEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_QUOTE_CALCULATE_DISCOUNTS, function(QuoteCalculateDiscountsEvent $event) {
    // $event->quote, $event->quoteItems, $event->discounts
});

EVENT_AFTER_BEGIN_CHECKOUT

Triggered after checkout begins.

use yii\base\Event;
use yui\craft\events\CheckoutBeginEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_BEGIN_CHECKOUT, function(CheckoutBeginEvent $event) {
    // $event->currency, $event->items, $event->value, $event->coupon
});

EVENT_AFTER_REGISTER_SHIPPING_METHOD_INFO

Triggered after shipping method info is registered.

use yii\base\Event;
use yui\craft\events\CheckoutAfterShippingMethodRegisterEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_REGISTER_SHIPPING_METHOD_INFO, function(CheckoutAfterShippingMethodRegisterEvent $event) {
    // $event->id, $event->code, $event->amount, $event->extra
});

EVENT_AFTER_REGISTER_PAYMENT_METHOD_INFO

Triggered after payment method info is registered.

use yii\base\Event;
use yui\craft\events\CheckoutAfterPaymentMethodRegisterEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_REGISTER_PAYMENT_METHOD_INFO, function(CheckoutAfterPaymentMethodRegisterEvent $event) {
    // $event->id, $event->code, $event->amount
});

EVENT_AFTER_PURCHASE_SUCCESS

Triggered after a successful purchase.

use yii\base\Event;
use yui\craft\events\CheckoutPurchaseEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_PURCHASE_SUCCESS, function(CheckoutPurchaseEvent $event) {
    // $event->order, $event->quote, $event->currency
});

EVENT_AFTER_PURCHASE_FAIL

Triggered after a failed purchase.

use yii\base\Event;
use yui\craft\events\CheckoutPurchaseEvent;
use yui\craft\services\CheckoutService;

Event::on(CheckoutService::class, CheckoutService::EVENT_AFTER_PURCHASE_FAIL, function(CheckoutPurchaseEvent $event) {
    // $event->order, $event->quote, $event->currency
});

EVENT_AFTER_CUSTOMER_LOGIN

Triggered after a customer logs in.

use yii\base\Event;
use yui\craft\events\CustomerLoginEvent;
use yui\craft\services\CustomerService;

Event::on(CustomerService::class, CustomerService::EVENT_AFTER_CUSTOMER_LOGIN, function(CustomerLoginEvent $event) {
    // $event->loggedIn
});

EVENT_AFTER_CUSTOMER_SIGN_UP

Triggered after a customer signs up.

use yii\base\Event;
use yui\craft\events\CustomerSignUpEvent;
use yui\craft\services\CustomerService;

Event::on(CustomerService::class, CustomerService::EVENT_AFTER_CUSTOMER_SIGN_UP, function(CustomerSignUpEvent $event) {
    // $event->customerId, $event->email, $event->signedUp
});

EVENT_REGISTER_CHECKOUT_BLOCK_TYPES

Triggered when registering block types for the checkout field-layout designer (Store Settings → Checkout designer). Use this to add your plugin's own drag-and-drop block to the checkout designer's block palette instead of building a separate, duplicate designer.

use yii\base\Event;
use craft\events\RegisterComponentTypesEvent;
use yui\craft\helpers\CheckoutDesignerHelper;
use mynamespace\fieldlayoutelements\MyCheckoutBlock;

Event::on(
    CheckoutDesignerHelper::class,
    CheckoutDesignerHelper::EVENT_REGISTER_CHECKOUT_BLOCK_TYPES,
    function(RegisterComponentTypesEvent $event) {
        $event->types[] = MyCheckoutBlock::class;
    }
);

$event->types is a plain array of FieldLayoutElement class strings (see Craft's field layout element docs); appending your class makes it selectable in the checkout designer's block chooser alongside the built-in blocks (contact, billing, shipping, payment, etc.).

Use EVENT_REGISTER_CHECKOUT_BLOCK_TYPES for anything that only appears during checkout (the Checkout form zone, or the Before checkout / After checkout zones around it — see CheckoutDesignerHelper::getZones()). For blocks on the cart page, or on the checkout result (success/failed) pages, use EVENT_REGISTER_CART_BLOCK_TYPES instead.

EVENT_REGISTER_CART_BLOCK_TYPES

Triggered when registering block types for the cart field-layout designer (Store Settings → Cart designer). The same event also governs the checkout result pages — success and failed — since those pages render a tab of the same underlying field layout as the cart designer; there is no separate result-page designer or event.

use yii\base\Event;
use craft\events\RegisterComponentTypesEvent;
use yui\craft\helpers\CartDesignerHelper;
use mynamespace\fieldlayoutelements\MyCartBlock;

Event::on(
    CartDesignerHelper::class,
    CartDesignerHelper::EVENT_REGISTER_CART_BLOCK_TYPES,
    function(RegisterComponentTypesEvent $event) {
        $event->types[] = MyCartBlock::class;
    }
);

Register listeners in your plugin's init() method (not a separate module — a shipping, payment, or marketing plugin registers its own blocks the same way):

// src/Plugin.php
use yii\base\Event;
use craft\events\RegisterComponentTypesEvent;
use yui\craft\helpers\CartDesignerHelper;
use yui\craft\helpers\CheckoutDesignerHelper;

public function init(): void
{
    parent::init();

    Event::on(
        CartDesignerHelper::class,
        CartDesignerHelper::EVENT_REGISTER_CART_BLOCK_TYPES,
        function(RegisterComponentTypesEvent $event) {
            $event->types[] = \mynamespace\fieldlayoutelements\MyCartBlock::class;
        }
    );

    Event::on(
        CheckoutDesignerHelper::class,
        CheckoutDesignerHelper::EVENT_REGISTER_CHECKOUT_BLOCK_TYPES,
        function(RegisterComponentTypesEvent $event) {
            $event->types[] = \mynamespace\fieldlayoutelements\MyCheckoutBlock::class;
        }
    );
}

Use EVENT_REGISTER_CART_BLOCK_TYPES for blocks on the cart page (any zone from CartDesignerHelper::getZones() — header, items, summary, empty-cart, etc.) and for blocks on the checkout result pages. On a result page the block simply appears in a different zone/tab (Checkout success, Checkout failed, or the detailed order-confirmation tabs) — the registration call is identical, only the zone the admin drags the block into changes.

Which event to use

Where the block should appear	Event
Checkout page (Before checkout / Checkout form / After checkout zones)	EVENT_REGISTER_CHECKOUT_BLOCK_TYPES
Cart page (any CartDesignerHelper::getZones() zone)	EVENT_REGISTER_CART_BLOCK_TYPES
Checkout result — success or failed page	EVENT_REGISTER_CART_BLOCK_TYPES (same field layout as the cart designer, different tab)

Writing the block class

A registered block is a FieldLayoutElement. Extend Craft's native craft\fieldlayoutelements\BaseUiElement (or craft\base\FieldLayoutElement directly) — the same base class Craft itself uses for its own field-layout UI elements — and implement at minimum formHtml() to render the block on the front end, and optionally settingsHtml() for the designer's block-settings panel:

namespace mynamespace\fieldlayoutelements;

use craft\base\ElementInterface;
use craft\fieldlayoutelements\BaseUiElement;
use craft\helpers\Cp;

class MyCartBlock extends BaseUiElement
{
    public string $heading = '';

    public function hasSettings(): bool
    {
        return true;
    }

    protected function settingsHtml(): ?string
    {
        return Cp::textFieldHtml([
            'label' => 'Heading',
            'id' => 'heading',
            'name' => 'heading',
            'value' => $this->heading,
        ]);
    }

    public function formHtml(?ElementInterface $element = null, bool $static = false): ?string
    {
        return \Craft::$app->getView()->renderTemplate('mynamespace/cart-block', [
            'heading' => $this->heading,
        ]);
    }
}

Your block's formHtml() template is rendered in-place in the cart/checkout/result Twig layout, in whichever zone the admin positioned it in the designer.

EVENT_REGISTER_MODULES

Triggered when dashboard modules are registered.

use yii\base\Event;
use yui\craft\events\RegisterDashboardModulesEvent;
use yui\craft\services\DashboardService;

Event::on(DashboardService::class, DashboardService::EVENT_REGISTER_MODULES, function(RegisterDashboardModulesEvent $event) {
    $event->modules[] = [
        'handle' => 'custom-module',
        'title' => 'Custom module',
    ];
});

EVENT_REGISTER_EMAIL_STYLES

Triggered when email styles are registered.

use yii\base\Event;
use yui\craft\events\RegisterEmailStyleEvent;
use yui\craft\services\EmailStyleService;

Event::on(EmailStyleService::class, EmailStyleService::EVENT_REGISTER_EMAIL_STYLES, function(RegisterEmailStyleEvent $event) {
    $event->styles['corporate'] = [
        'label' => 'Corporate',
        'description' => 'A clean corporate email style',
        'css' => '@web/assets/email/corporate.min.css',
        'template' => 'my-module/email/themes/corporate',
    ];
});

EVENT_BEFORE_GIFT_CARD_GENERATED

Triggered before a gift card PDF is generated.

use yii\base\Event;
use yui\craft\events\GiftCardVoucherBeforeGeneratorEvent;
use yui\craft\services\marketing\GiftCardService;

Event::on(GiftCardService::class, GiftCardService::EVENT_BEFORE_GIFT_CARD_GENERATED, function(GiftCardVoucherBeforeGeneratorEvent $event) {
    // $event->item, $event->variables
});

EVENT_AFTER_GIFT_CARD_GENERATED

Triggered after a gift card PDF is generated.

use yii\base\Event;
use yui\craft\events\GiftCardVoucherAfterGeneratorEvent;
use yui\craft\services\marketing\GiftCardService;

Event::on(GiftCardService::class, GiftCardService::EVENT_AFTER_GIFT_CARD_GENERATED, function(GiftCardVoucherAfterGeneratorEvent $event) {
    // $event->item, $event->variables, $event->asset
});

EVENT_AFTER_GIFT_CARD_CODES_GENERATED

Triggered after gift card codes are generated.

use yii\base\Event;
use yui\craft\events\GiftCardVoucherCodeGeneratorEvent;
use yui\craft\services\marketing\GiftCardService;

Event::on(GiftCardService::class, GiftCardService::EVENT_AFTER_GIFT_CARD_CODES_GENERATED, function(GiftCardVoucherCodeGeneratorEvent $event) {
    // $event->orderId, $event->codes
});

EVENT_AFTER_ORDER_STATUS_CHANGE

Triggered after an order status changes.

use yii\base\Event;
use yui\craft\events\OrderStatusChangeEvent;
use yui\craft\services\OrdersService;

Event::on(OrdersService::class, OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE, function(OrderStatusChangeEvent $event) {
    // $event->statusFrom, $event->statusTo, $event->orderId
});

EVENT_AFTER_ORDER_METHOD_UPDATE

Triggered after order shipping/payment methods are updated.

use yii\base\Event;
use yui\craft\events\OrderMethodUpdateEvent;
use yui\craft\services\OrdersService;

Event::on(OrdersService::class, OrdersService::EVENT_AFTER_ORDER_METHOD_UPDATE, function(OrderMethodUpdateEvent $event) {
    // $event->order
});

EVENT_AFTER_ORDER_COLLECT_ATTACHMENTS

Triggered after order attachments are collected.

use yii\base\Event;
use yui\craft\events\OrderAfterCollectAttachments;
use yui\craft\services\OrdersService;

Event::on(OrdersService::class, OrdersService::EVENT_AFTER_ORDER_COLLECT_ATTACHMENTS, function(OrderAfterCollectAttachments $event) {
    // $event->order, $event->attachments
});

EVENT_AFTER_PRODUCT_VIEW

Triggered after a product is viewed.

use yii\base\Event;
use yui\craft\events\ProductViewEvent;
use yui\craft\services\Products;

Event::on(Products::class, Products::EVENT_AFTER_PRODUCT_VIEW, function(ProductViewEvent $event) {
    // $event->currency, $event->value, $event->items
});

EVENT_AFTER_SEARCH

Triggered after a search is performed.

use yii\base\Event;
use yui\craft\events\SearchEvent;
use yui\craft\services\SearchService;

Event::on(SearchService::class, SearchService::EVENT_AFTER_SEARCH, function(SearchEvent $event) {
    // $event->searchTerm
});

EVENT_REGISTER_THEMES

Triggered when themes are registered.

use yii\base\Event;
use yui\craft\events\RegisterThemeEvent;
use yui\craft\services\ThemeService;

Event::on(ThemeService::class, ThemeService::EVENT_REGISTER_THEMES, function(RegisterThemeEvent $event) {
    $event->themes['custom'] = [
        'label' => 'Custom Theme',
        'description' => 'My custom theme',
        'cartCss' => '@web/assets/themes/cart-custom.css',
        'checkoutCss' => '@web/assets/themes/checkout-custom.css',
    ];
});

EVENT_REGISTER_TRIGGER_DEFINITIONS

Triggered when flow trigger definitions are registered.

use yii\base\Event;
use yui\craft\events\RegisterFlowDefinitionsEvent;
use yui\craft\services\marketing\FlowService;

Event::on(FlowService::class, FlowService::EVENT_REGISTER_TRIGGER_DEFINITIONS, function(RegisterFlowDefinitionsEvent $event) {
    $event->classList[] = \App\Flow\Triggers\MyCustomTrigger::class;
});

EVENT_REGISTER_ACTION_DEFINITIONS

Triggered when flow action definitions are registered.

use yii\base\Event;
use yui\craft\events\RegisterFlowDefinitionsEvent;
use yui\craft\services\marketing\FlowService;

Event::on(FlowService::class, FlowService::EVENT_REGISTER_ACTION_DEFINITIONS, function(RegisterFlowDefinitionsEvent $event) {
    $event->classList[] = \App\Flow\Actions\MyCustomAction::class;
});

EVENT_REGISTER_CONDITION_DEFINITIONS

Triggered when flow condition definitions are registered.

use yii\base\Event;
use yui\craft\events\RegisterFlowDefinitionsEvent;
use yui\craft\services\marketing\FlowService;

Event::on(FlowService::class, FlowService::EVENT_REGISTER_CONDITION_DEFINITIONS, function(RegisterFlowDefinitionsEvent $event) {
    $event->classList[] = \App\Flow\Conditions\MyCustomCondition::class;
});

EVENT_REGISTER_LOGIC_DEFINITIONS

Triggered when flow logic definitions are registered.

use yii\base\Event;
use yui\craft\events\RegisterFlowDefinitionsEvent;
use yui\craft\services\marketing\FlowService;

Event::on(FlowService::class, FlowService::EVENT_REGISTER_LOGIC_DEFINITIONS, function(RegisterFlowDefinitionsEvent $event) {
    $event->classList[] = \App\Flow\Logic\MyCustomLogic::class;
});

EVENT_MODIFY_TOTAL_LABELS

Triggered when cart and checkout total labels are resolved.

use yii\base\Event;
use yui\craft\events\TotalLabelsEvent;
use yui\craft\web\twig\CraftVariableBehavior;

Event::on(CraftVariableBehavior::class, CraftVariableBehavior::EVENT_MODIFY_TOTAL_LABELS, function(TotalLabelsEvent $event) {
    $event->addLabelAfter('shipping_method', 'service_fee', 'Service Fee');
});

Where to register event listeners

Register listeners in your module's init() method, typically in modules/YourModule.php:

public function init(): void
{
    parent::init();

    Event::on(
        CartService::class,
        CartService::EVENT_AFTER_ADD_TO_CART,
        function (CartAddToEvent $event) {
            // your logic here
        }
    );
}

Craft Module

If you don't have a custom module yet, see Craft CMS — Module guide for how to create one.