Skip to content

Shipping Integration API for Hyvä Checkout

The Shipping Integration API provides the structure for registering shipping methods in Hyvä Checkout and configuring display properties like icons. Shipping methods that require customer interaction (pickup location selection, delivery time slots) can register custom templates and optionally use Magewire components for dynamic functionality.

Registering a Shipping Method

Any shipping method enabled in Magento system configuration automatically appears in the checkout shipping step. Shipping methods requiring additional customer input must register a template block to display their UI when selected.

Layout XML Registration

Register shipping method templates as children of the checkout.shipping.methods block in layout/hyva_checkout_components.xml. The block alias (as attribute) must follow the pattern carrierCode_methodCode.

Shipping Method Block Registration
<!-- File: view/frontend/layout/hyva_checkout_components.xml -->

<referenceBlock name="checkout.shipping.methods">
    <block name="checkout.shipping.method.custom-shipping"
           as="carrierCode_methodCode"
           template="Hyva_Checkout::component/shipping/method/custom-shipping.phtml"/>
</referenceBlock>

Block Alias Format

The as attribute must start with the carrier code, followed by an underscore, then the method code (e.g., flatrate_flatrate, tablerate_bestway). This enables Hyvä Checkout to associate the template with the correct shipping method.

The template renders when the customer selects the shipping method. Template naming conventions are flexible, but following the example pattern improves maintainability.

Adding Magewire Component Functionality

For shipping methods requiring dynamic server interaction (e.g., fetching pickup locations, calculating delivery windows), add a Magewire component by specifying the magewire argument.

Shipping Method with Magewire Component
<referenceBlock name="checkout.shipping.methods">
    <block name="checkout.shipping.method.custom-shipping"
           as="carrierCode_methodCode"
           template="Hyva_Checkout::component/shipping/method/custom-shipping.phtml">
        <arguments>
            <argument name="magewire" xsi:type="object">
                Hyva\Checkout\Magewire\Checkout\Shipping\CustomShipping
            </argument>
        </arguments>
    </block>
</referenceBlock>

The Magewire component handles server-side logic while the template manages the UI. See the Magewire documentation for component implementation details.

Shipping Method Display Properties

Configure frontend display properties using metadata block arguments. Metadata extends shipping methods with frontend features without modifying the Magento shipping method object.

Shipping Method Icon

Display an icon next to the shipping method title using SVG or image files.

Since: 1.1.27

SVG Icons

Load SVG icons from a Hyvä icon pack extension or from your module's view/frontend/web/svg folder.

Shipping Method with SVG Icon
<referenceBlock name="checkout.shipping.methods">
    <block name="checkout.shipping.method.tablerate_bestway"
           as="tablerate_bestway">
        <arguments>
            <argument name="metadata" xsi:type="array">
                <item name="icon" xsi:type="array">
                    <!-- Icon path: icon-pack-name/icon-name -->
                    <item name="svg" xsi:type="string">heroicons/outline/truck</item>
                    <!-- Optional: SVG attributes -->
                    <item name="attributes" xsi:type="array">
                        <item name="fill" xsi:type="string">none</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

For information on using SVG icons with the SvgIcons view model, see the SvgIcons documentation.

Image Icons

Load images from your module's view/frontend/web/ directory using the src argument.

Shipping Method with Image Icon
<referenceBlock name="checkout.shipping.methods">
    <block name="checkout.shipping.method.tablerate_bestway"
           as="tablerate_bestway">
        <arguments>
            <argument name="metadata" xsi:type="array">
                <item name="icon" xsi:type="array">
                    <!-- Image path processed by Magento asset repository -->
                    <item name="src" xsi:type="string">Magento_Theme::calendar.png</item>
                    <!-- Optional: HTML attributes for the img tag -->
                    <item name="attributes" xsi:type="array">
                        <item name="width" xsi:type="number">100</item>
                        <item name="loading" xsi:type="string">lazy</item>
                        <item name="alt" xsi:type="string" translate="true">Calendar icon</item>
                        <item name="data-my-custom-attribute" xsi:type="string">Hello World!</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>