Skip to content

Theming Store Credit

Store Credit ships five storefront templates, and every one of them can be overridden from your Hyvä child theme the ordinary way. This page maps out what renders where, which view models feed each template, and how the pieces stay in sync.

Storefront Templates

Copy any of these into app/design/frontend/<Vendor>/<theme>/Hyva_StoreCredit/templates/ to override it.

Template Where it renders
account/store-credit.phtml The Store Credit page in My Account: the balance card and the credit history table.
cart/minicart-store-credit.phtml The apply and remove panel, used on both the cart page and in the cart drawer.
checkout/store-credit.phtml The apply and remove panel in the Hyvä Checkout order summary.
header/store-credit-link.phtml The balance link in the header account menu.
page/js/api/v1/navigation/refresh-store-credit.phtml A script block that re-refreshes the checkout component on step navigation.

Layout Handles

Store Credit hooks into six frontend layout handles. Override any of these in your theme to move a block, change its template, or remove it.

Handle What it adds
default.xml The header balance link into header.customer.logged.in.links at sort order 250, and the store credit panel into the cart-drawer.totals.before container.
checkout_cart_index.xml The store credit panel into checkout.cart.totals.container.
customer_account.xml The Store Credit link into customer_account_navigation at sort order 250.
storecredit_account_index.xml The My Account page itself, as a 2columns-left page with the account navigation, marked cacheable="false".
hyva_checkout_components.xml The store-credit block into checkout.price-summary.section, before the total segments.
sales_order_view.xml, sales_order_invoice.xml, sales_order_creditmemo.xml The store credit totals line into the order, invoice, and credit memo totals.

The cart and drawer blocks are wrapped in ifconfig="hyva_store_credit/general/enabled", so they disappear entirely when store credit is off rather than rendering an empty panel. Keep that attribute if you re-declare the blocks in your own layout.

View Models and Blocks

Hyva\StoreCredit\ViewModel\Account\StoreCredit feeds the My Account template. It exposes getBalanceAmount() and getFormattedBalance(), isHistoryVisible(), getHistory() (the most recent 50 entries with a non-zero delta, newest first), getEventTypeLabel(), formatAmount(), and the reference helpers getReferenceUrl(), getReferenceLabel(), and getCustomerReason(). Because getCustomerReason() falls back to the reference label, a spend with no external reason still reads as the order it paid for.

Hyva\StoreCredit\Block\Order\Totals adds the negative Store Credit line before the grand total on order, invoice, and credit memo totals, in both the storefront and the admin.

The Checkout Component

Hyva\StoreCredit\Magewire\Checkout\StoreCredit is the Magewire component behind the checkout panel. Its public properties are what the template binds to: isEnabled, loggedIn, applied, hasBalance, availableLabel, and appliedLabel. Its actions are applyStoreCredit(), removeStoreCredit(), and refresh().

The component emits store_credit_applied and store_credit_revoked, and Hyva\StoreCredit\Plugin\Checkout\PriceSummaryListeners registers both on Hyvä Checkout's PriceSummary component as refresh triggers. It also listens to every event that could change the order total, so the panel is never showing a stale figure. See the Event Reference for the full listener map.

The root element carries the class store-credit-checkout, which the module's end-to-end tests use as their selector. Keep it on your override if you want those tests to keep passing.

Cart and Header Components

The cart panel and the header link are Alpine components, initMinicartStoreCredit and initStoreCreditHeaderLink, registered through alpine:init and Alpine.data() and declared to the CSP with HyvaCsp::registerInlineScript(). If you copy either template, keep the CSP registration or the script will be blocked. See Nonce and SHA Hashes for how that registration works.

Both read their state from the hyva-store-credit private content section rather than from the rendered page, which is what lets them live inside cached HTML. The cart panel posts a form key to storecredit/cart/apply or storecredit/cart/remove, then dispatches reload-customer-section-data so the drawer, the cart page, and the header balance all update together.

The Private Content Section

Hyva\StoreCredit\CustomerData\StoreCredit provides the hyva-store-credit section. For a guest, or when store credit is disabled, it returns only is_enabled, logged_in, and has_balance. For a logged-in customer with the feature on it also returns balance, formatted_balance, applied, applied_amount, formatted_applied, total_after_credit, and formatted_total_after_credit.

The section is invalidated by cart apply and remove, checkout/cart/add, customer logout, and the order success actions for both Magento's checkout and Hyvä Checkout. If your build introduces another action that changes a cart total, add it to your own sections.xml so the panel does not go stale.

Tailwind CSS

Store Credit ships view/frontend/tailwind/tailwind.config.js, which points Tailwind at the module's own templates. The module registers itself for config merging through an observer on hyva_config_generate_before, so its classes are picked up automatically when you compile your theme. See Compatibility Modules Technical Deep Dive for how module Tailwind configs are merged.

If you override a template and introduce new utility classes, they are picked up from your theme's own content paths as usual. If you remove classes from an override, remember the module's config still scans the original templates, so unused classes may still be generated.