Hyvä Checkout Frontend API Events

The Hyvä Checkout Frontend API dispatches JavaScript events at key points during the checkout lifecycle. These events enable custom integrations to execute code at precise moments—after initialization, during navigation, when methods are selected, or when storage changes occur.

Listening for Events

All checkout events are dispatched on the window object using the standard browser CustomEvent API. Listen for events using window.addEventListener():

Basic event listener pattern

window.addEventListener('checkout:event:name', (event) => {
    // Access event data via event.detail
    console.log(event.detail);
});

API Initialization Events

The checkout API initializes in stages, with each sub-namespace becoming available at different times. These events let you execute code when specific parts of the API are ready.

checkout:init:* — Sub-namespace initialization

Listen for a specific sub-namespace to finish initializing by replacing * with the namespace name. Available namespaces include: storage, evaluation, payment, validation, navigation, messenger, main, and config.

Wait for storage sub-namespace

window.addEventListener('checkout:init:storage', () => {
    // The hyvaCheckout.storage namespace is now available
    console.log('Storage initialized');
});

checkout:init:after — All sub-namespaces initialized

Use this event when you need all API sub-namespaces to be ready before executing your code. This is the most common initialization event for general integrations.

checkout:init:done — Final initialization complete

For rare scenarios requiring code to run after all initialization callbacks have completed, use checkout:init:done. This event fires after checkout:init:after handlers have all executed.

Storage Events

These events fire when data in the checkout session storage changes. Use storage events to react to data updates made by other components.

checkout:storage:changed — Storage value modified

Fires whenever any value in the checkout session storage is added, updated, or removed. Use this event to synchronize UI state with storage changes made by other checkout components.

Validation Events

Validation events provide visibility into the validation system's registration and execution lifecycle.

checkout:validation:register — Validator registered

Fires when a validation callback is registered with the validation stack. Use this event for debugging or to track which validators are active.

Navigation Events

Navigation events fire during checkout step transitions. Use these events to execute code when customers move between checkout steps or when steps finish loading.

checkout:step:loaded — Step content rendered

Fires when a checkout step has finished loading and is visible to the customer. The event payload distinguishes between the initial page load (preceding) and dynamic navigation (subsequent).

Payload Property	Type	Description
event.detail.route	string	The step identifier (e.g., shipping, payment)
event.detail.subsequent	boolean	true for navigation, false for initial page load

Track step loading

window.addEventListener('checkout:step:loaded', (event) => {
    const loadType = event.detail.subsequent ? 'navigation' : 'initial';
    console.log(`Step "${event.detail.route}" loaded via ${loadType}`);
});

checkout:navigation:success — Step navigation completed

Fires after a customer successfully navigates to the next or previous step. Unlike checkout:step:loaded, this event does not fire for the initial step shown on page load—only for explicit navigation actions.

Shipping Events

Shipping events fire when customers interact with shipping method options. Use these events to trigger shipping-related integrations or update UI elements based on the selected method.

checkout:shipping:method-activate — Shipping method selected

Fires when a customer selects a shipping method or when the shipping step renders with a pre-selected method. The event payload contains the shipping method code.

Payload Property	Type	Description
event.detail.method	string	The selected shipping method code

React to shipping method selection

window.addEventListener('checkout:shipping:method-activate', (event) => {
    console.log(`Selected shipping method: ${event.detail.method}`);
    // Trigger delivery date picker, update totals display, etc.
});

Payment Events

Payment events fire during payment method interactions. Use these events to coordinate PSP SDK initialization, track method selection, or respond to payment component state changes.

checkout:payment:method-activate — Payment method selected

Fires when a customer selects a payment method or when the payment step renders with a pre-selected method. The event payload contains the payment method code.

Payload Property	Type	Description
event.detail.method	string	The selected payment method code

Initialize PSP SDK on method selection

window.addEventListener('checkout:payment:method-activate', (event) => {
    if (event.detail.method === 'my_psp_method') {
        // Initialize the PSP SDK when this method is selected
        initializeMyPspSdk();
    }
});

payment:method:registered — Payment method available

Fires when a JavaScript-driven payment method is registered with the Frontend API. Use this event to verify that payment integrations have loaded correctly.

payment:method:success — Payment component ready

Fires when the payment component has rendered successfully without backend errors. This confirms the payment step is ready for customer interaction (a method is selected, no validation errors).

Evaluation Events

Evaluation events provide insight into the Evaluation API processing cycle. These events are primarily useful for debugging or advanced integration scenarios.

checkout:evaluation-process:after — Evaluation results processed

Fires after all evaluation results from the backend have been processed by the frontend. In most cases, you won't need this event—use specific validation or navigation events instead. However, if you need to know when a particular evaluation result has finished processing, this event provides that visibility.

Utility Events

These events provide general-purpose functionality that can be triggered or observed by any component.

clear-messages — Clear flash messages

Dispatch this event to clear all flash messages currently displayed on the page. Components displaying custom messages can also listen for this event to clear their own message displays.

Clear all checkout messages

// Dispatch to clear messages
window.dispatchEvent(new Event('clear-messages'));

// Listen to clear custom component messages
window.addEventListener('clear-messages', () => {
    myComponent.clearCustomMessages();
});