Store Credit Event Reference

Store Credit is designed to be extended through events rather than through class rewrites. It dispatches five Magento events of its own around reading and writing balances, observes nine Magento events to keep the ledger in step with orders, and emits two Magewire events on the storefront. This page is the reference for all of them.

Store Credit uses its own events internally too: the balance change emails are an observer on hyva_store_credit_balance_changed, not a hardcoded call. Anything the module can do to itself, your module can do the same way.

Events Store Credit Dispatches

These are the extension points for your own code. All five are dispatched by Hyva\StoreCredit\Model\Ledger\LedgerWriter and Hyva\StoreCredit\Model\Ledger\BalanceReader.

hyva_store_credit_append_before

Fired inside LedgerWriter::append() after the entry has been validated and after the idempotency check, but before the database transaction opens. Nothing has been written yet.

This is the only veto point in the write path. Throwing an exception from an observer here aborts the write before any database work happens, which makes it the right place for a policy check such as refusing credit to a customer group or capping how much credit a single adjustment may add.

hyva_store_credit_append_after

Fired inside LedgerWriter::append() after the transaction has been committed. The entry now has its ID, its balance_after, and its resolved currency.

Use this when you need the written entry itself, for example to push a row into a reporting table or an external accounting system.

hyva_store_credit_balance_changed

Fired immediately after hyva_store_credit_append_after, with the change flattened into scalars so an observer does not have to unpack the entry. This is the event most integrations want.

This event fires after the balance change has been committed, so it cannot veto anything. That is deliberate: a failing notification must never roll back a customer's credit.

hyva_store_credit_get_balance_before

Fired at the start of BalanceReader::getBalance(), before the projection is read.

hyva_store_credit_get_balance_after

Fired at the end of BalanceReader::getBalance(), with the resolved balance.

The balance object is mutable, so an observer can rewrite the amount before it reaches the caller. That makes it possible to layer promotional credit on top of the stored balance without writing it to the ledger, but it also means an incorrect observer here makes every balance in the system wrong. Read carefully before reaching for it.

Observing a Store Credit Event

Observers are registered the ordinary Magento way. This example logs every balance change to your own audit table.

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="hyva_store_credit_balance_changed">
        <observer name="vendor_module_record_credit_change"
                  instance="Vendor\Module\Observer\RecordCreditChange"/>
    </event>
</config>

The observer reads the flattened payload straight off the event:

<?php
declare(strict_types=1);

namespace Vendor\Module\Observer;

use Hyva\StoreCredit\Model\Ledger\EventType;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class RecordCreditChange implements ObserverInterface
{
    public function __construct(private readonly \Vendor\Module\Model\AuditWriter $auditWriter)
    {
    }

    public function execute(Observer $observer): void
    {
        $event = $observer->getEvent();
        $eventType = (int) $event->getData('event_type');

        // EventType classifies the change, so no need to test the sign of the delta.
        $this->auditWriter->record(
            (int) $event->getData('customer_id'),
            (int) $event->getData('website_id'),
            (float) $event->getData('delta'),
            EventType::getLabel($eventType),
            EventType::isCredit($eventType)
        );
    }
}

Magento Events Store Credit Observes

Store Credit already hooks these events. Check this table before adding an observer of your own, so you know what has run before yours.

Magewire and Browser Events

On the storefront, the checkout component talks to the rest of checkout through Magewire events rather than direct calls.

Hyva\StoreCredit\Magewire\Checkout\StoreCredit emits:

• store_credit_applied when the customer applies their credit.
• store_credit_revoked when the customer removes it.

Hyva\StoreCredit\Plugin\Checkout\PriceSummaryListeners adds both of those to Hyvä Checkout's PriceSummary component as refresh listeners, which is how the order summary updates itself when credit goes in or out. If you build a component that needs to react to store credit, listen for the same two events.

The store credit component listens to everything that could change the order total, all mapped to refresh: shipping_method_selected, payment_method_selected, coupon_code_applied, coupon_code_revoked, shipping_address_saved, shipping_address_activated, billing_address_saved, and billing_address_activated.

In the browser, two more events matter:

• checkout:step:loaded with detail.subsequent re-refreshes the store credit component, which is what keeps the panel alive when the customer navigates forward to payment and back again.
• private-content-loaded drives the cart and minicart panels, which dispatch reload-customer-section-data after applying or removing credit to refresh the hyva-store-credit section.

Related Topics

• Store Credit Service API - writing to the ledger from your own code, rather than reacting to it.
• Store Credit Architecture - idempotency keys, the projection, and the write guards these events sit around.
• Theming Store Credit - the components that emit and listen to the Magewire events.