Skip to content

Shipping Integration API

Register a Shipping method

Similar to the payment method any shipping method that is enabled for a store in the system configuration will be listed in the shipping step. This only makes sense for shipping methods that do not need to collect any information from the customer.

If your shipping method requires additional customer input, you may need to develop a custom shipping integration that handles the necessary user interaction and data collection.

Layout XML

To display content when the shipping method is selected, a block for the shipping method needs to be declared as a child of the checkout.shipping.methods block in the layout/hyva_checkout_components.xml file.

For example: 

<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>

The block alias (as="...") has to start with the carrier code followed by an underscore then the method code.

The name of the shipping block in layout XML and the template name are not required to follow a specific convention, but we suggest you follow the example above.

If you would like the template to become a Magewire component, then you can do so by simply adding the Magewire argument like you would elsewhere:

<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>

Additional display properties

Common frontend display properties, such as a shipping provider logo, can be added to shipping methods as metadata. Metadata allows shipping methods to be expanded with frontend features without the need to modify the Magento shipping method object.

Metadata is added to a shipping method by specifying block arguments for the method in layout XML.

Currently, only icons are supported. More may be added in the future.

Shipping Method Icon

To display an icon for a specific shipping method, an argument with the name icon and the type array has to be added to the metadata array argument. Hyvä checkout allows the following types of icons to be used:

Type Argument Name Version
SVG svg >= 1.1.27
Image src >= 1.1.27
SVGs

When opting to provide an SVG, the icon path is then specified in an svg child array item. Icons can be loaded from a Hyvä icon pack extension, or they can be SVG files that are added in the shipping integration module's view/frontend/web/svg folder.

An additional array of attributes can be specified if needed, in a similar way as you would when using the SvgIcons view model.

For example: 

<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">
                    <item name="svg" xsi:type="string">heroicons/outline/truck</item>
                    <!-- optional attributes, specify as needed -->
                    <item name="attributes" xsi:type="array">
                        <item name="fill" xsi:type="string">none</item>
                    </item>
                </item>
            </argument>
        </arguments>
    </block>
</referenceBlock>

Images

When opting to provide an image, the image path is then specified in a src child array item. The argument value can be anything that can be processed by the Magento\Framework\View\Asset\Repository::getUrl() function, typically you will find this will be files within a module's view/{{area}}/web/ directory.

An additional array of attributes can be specified if required. These are specified as key => value pairs that translate into HTML attribute names and their values respectively.

For example: 

<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">
                    <item name="src" xsi:type="string">Magento_Theme::calendar.png</item>
                    <!-- optional attributes, specify as needed -->
                    <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>