php wordpress woocommerce hook-woocommerce

How to append a clickable link to WooCommerce custom fee name on Checkout?

In WooCommerce, I have added a custom fee which applies for products with shipping class "dangerous goods" (dangerous-goods). I now want to append/add a link to this custom fee name on the checkout page, that directs customers to the shipping policy explaining the fee.

Please note, that I use woocommerce legacy shortcode for my checkout page [woocommerce_checkout].

However, when adding a link to the fee name using the woocommerce_cart_calculate_fees hook, WooCommerce doesn't render HTML in the fee name, because it escapes the fee label. As a result, the link won't display as a clickable link but rather plain text.

Example:

// Add the handling fee with a link
   $fee_label = 'Handling fee - dangerous goods (<a href="https://example.com" target="_blank">Learn More</a>)';
   $cart->add_fee( $fee_label, $handling_fee, true );

Outcome:

Alternative solution:

I then tried to use the woocommerce_cart_totals_fee_html, filter hook from this SO solution, that allows to modify or customize the rendered HTML output of the fee displayed.

add_filter( 'woocommerce_cart_totals_fee_html', 'custom_handling_fee_link', 10, 2 );
function custom_handling_fee_link( $fee_html, $fee ) {
    // Check if the current page is the checkout page & fee name
    if ( is_checkout() && $fee->name === 'Handling fee - dangerous goods' ) {
        $fee_html .= ' <span style="display:block;"><a href="https://example.com" target="_blank">(Learn More)</a></span>';
    }
    return $fee_html;
}

This successfully appends the link as an interactive hyperlink, but adds it after the fee itself rather than appending it to the fee name:

Expected result: This is how i expect the result to look like.

Question:

As I understand, it's not possible to bypass the escaping process directly in the fee name itself, as WooCommerce's internal sanitization ensures that fee names remain clean and safe. Given this limitation, are there alternative hooks or filters that could allow me to append a link to the fee name on the front-end?

Thought I prefer a PHP-based solution, I am also willing to consider JavaScript if PHP alone cannot achieve this.

Also, the fee name displayed in invoices, emails, or backend must remain clean without the link. So only show the link in the fee name, front-end on the checkout-page.

Solution

I found multiple solutions to my question, while dealing with my question. All these solutions have in common that they only render the link on the front-end of the checkout page. I have tried and tested each one of these solutions, and I will try and explain them.

Please note:

These solutions are specifically tailored to be applicable only to setups using the legacy checkout shortcode. They are not compatible and will not work with Checkout Blocks, which have been enabled by default in WooCommerce for a few years. Checkout Blocks use a completely different architecture and rendering method.

Solution 1 - PHP solution for appending link to fee using filter:

If you are looking for a simple solution using WooCommerce filter, the woocommerce_cart_totals_fee_html filter is likely the best option. WooCommerce currently doesn't provide other filters specifically targeting the fee name output for appending links on the front-end. This hook works well if you're okay with the link displaying alongside the fee, instead of directly within the fee name.

Example:

add_filter( 'woocommerce_cart_totals_fee_html', 'custom_handling_fee_link', 10, 2 );
function custom_handling_fee_link( $fee_html, $fee ) {
    // Check if the current page is the checkout page & fee name
    // Change fee name with name of your own fee (exact match)
    if ( is_checkout() && $fee->name === 'Handling fee - dangerous goods' ) {
        $fee_html .= ' <span style="display:block;"><a href="https://example.com" target="_blank">(Learn More)</a></span>';
    }
    return $fee_html;
}

The code should be added to your functions.php file, of your active child theme. The pro of this solution is, it's simple to implement, but link appears outside the fee name.

Solution 2 - Template override to append link to fee name:

Another option is to override and edit the woocommerce template file review-order.php. This is the file responsible for rendering the checkout table. For this you will need to create a child theme so your customizations remain intact during updates. Here are the steps:

Copy the template file from: wp-content/plugins/woocommerce/templates/checkout/review-order.php
Paste it into your child theme under: wp-content/themes/your-child-theme/woocommerce/checkout/review-order.php

Locate the section of the table, within the template that outputs the fees. Should look something like this:

<tr class="fee">
    <th><?php echo esc_html( $fee->name ); ?></th>
    <td><?php wc_cart_totals_fee_html( $fee ); ?></td>
</tr>

Update the code to append the clickable link to the fee name, using condition:

<tr class="fee">
    <th><?php echo esc_html( $fee->name );
        // Check for fee name and echo link
        if ( 'Handling fee - dangerous goods' === $fee->name ) {
            echo ' <a href="https://example.com" target="_blank" rel="noopener noreferrer">(Learn More)</a>';
        }
        ?>
    </th>
    <td><?php wc_cart_totals_fee_html( $fee ); ?></td>
</tr>

I don't recommend this approach, unless you know what you are doing. Also, keep in mind that themes (especially custom themes) may update, so it's essential to maintain your customizations carefully. Document the changes you've made to ensure compatibility with future WooCommerce updates. So while there is greater control, it requires careful maintenance during updates.

Solution 3 - Appending link to fee name using Javascript

It is possible to use JavaScript (via jQuery) to add the clickable link to the fee name. I managed to do this with the following code, which I will try to explain via comments:

// Hook the function to the footer of the website
add_action('wp_footer', 'append_fee_link_to_custom_fee_via_js');
function append_fee_link_to_custom_fee_via_js() {
    // Only run on checkout page
    if (is_checkout()) {
        ?>
        <script type="text/javascript">
            jQuery(document).ready(function($) {
                // Function to add the link to the fee name
                function addReadMoreLink() {
                    // Target the specific fee row and avoid redundant operations
                    $("tr.fee").each(function() {
                        const feeLabel = $(this).find("th").text().trim();
                        
                        // If the fee name matches and the link doesn't already exist, append the link
                        if (feeLabel === 'Handling fee - dangerous goods' && !$(this).find("th a").length) {
                            $(this).find("th").append(
                                $('<a>', {
                                    href: 'https://example-link.com', // Replace with your own link
                                    text: ' Read more', // Text for the link
                                    target: '_blank', // Open link in a new tab
                                    rel: 'noopener noreferrer', // Security attributes for the link
                                    style: 'color: #0073aa; font-size: 14px;' // Custom styling for the link
                                })
                            );
                        }
                    });
                }

                // Execute the function when the page is loaded
                addReadMoreLink();
                
                // Re-run the function after WooCommerce updates the checkout via AJAX
                // Ensures the link remains visible only when necessary
                $(document.body).on('updated_checkout', function() {
                    addReadMoreLink();
                });
            });
        </script>
        <?php
    }
}

This code can be added to functions.php file of your active child theme. Alternatively, you can move the JavaScript code to a separate .js file and enqueue it using wp_enqueue_script.

There probably is a better and cleaner JS solution than the one I provided, since my knowledge of JavaScript isn't very advanced. But it adds the link to the fee name, which was my goal.

Conclusion:

In all my solutions, I check for exact fee name match, this means that if you change your fee name, you will need to adjust accordingly.
All the solutions assume you have already created your custom fee, using woocommerce_cart_calculate_fees hook. For more reading on how to add custom fee.

Each solution has its strengths and limitations. If you prefer simplicity and don’t mind the link appearing next to the fee, Solution 1 (PHP filter) is a great choice. For those comfortable with template customizations, Solution 2 offers complete control, though it requires maintenance during updates. Finally, Solution 3 (JavaScript) provides flexibility for dynamic front-end updates, without modifying PHP code.