This guide covers developer-related customization options, including available hooks, template adjustments, and styling modifications via CSS. Use this documentation to extend or modify the Free Shipping Label plugin to fit your needs.
Adding PHP code: Add custom code to your child theme’s functions.php file or use a plugin like Code Snippets to safely insert functions.
Adding CSS: For customizations, add your styles to Appearance → Customize → Additional CSS or your child theme’s stylesheet (style.css)
Avoid adding code directly to your parent theme’s files, as it will be overwritten when the theme updates.
WooCommerce Hooks for Free Shipping Label
Our plugin relies on WooCommerce hooks within templates. Many themes and plugins include custom cart, mini-cart, and checkout templates, sometimes omitting these hooks and replacing them with custom HTML for layout and styling. While this isn’t necessarily a problem, it can prevent the progress bar from displaying.
If you are using the free version of Free Shipping Label and the progress bar isn’t appearing, you may need to manually edit your theme’s WooCommerce templates. This requires some knowledge of PHP, HTML, and CSS.
We don’t provide step-by-step instructions since template structures vary by theme. However, below are the WooCommerce hooks our plugin relies on. If they are missing, you can add them to your templates—but be careful, as this may duplicate existing elements, requiring further adjustments.
Cart page hook
do_action( 'woocommerce_proceed_to_checkout' );
Minicart widget hook
do_action( 'woocommerce_widget_shopping_cart_before_buttons' );
Checkout hook
do_action( 'woocommerce_review_order_before_submit' );
Positioning the Progress Bar Shortcode via Hook
In the Pro version, the progress bar can be displayed using the [fsl-progress-bar] shortcode.
You can insert this shortcode directly in the WordPress editor, your favorite page builder, or use it as a Gutenberg block. However, if you need to place it in a specific position where a page builder doesn’t have access, you can insert it via a hook.
Inserting the Progress Bar via Hook
To add the progress bar at a custom location, use the echo do_shortcode() function within a WooCommerce or WordPress action hook.
Here are a few examples:
These examples demonstrate how to integrate the progress bar into different parts of your WooCommerce templates using hooks. The positions shown are already available in the Pro version and can be adjusted directly in the settings panel. This is simply an example of how to implement the progress bar via a hook.
Your theme or a third-party plugin may have its own specific hooks where the progress bar can be inserted. Adjust the hook placement based on your layout and desired position.
Display Progress Bar Before the Cart Totals
add_action( 'woocommerce_before_cart_totals', function() {
echo do_shortcode('[fsl-progress-bar]');
});Display Progress Bar at the Top of the Checkout Page
add_action( 'woocommerce_before_checkout_form', function() {
echo do_shortcode('[fsl-progress-bar]');
});Display Progress Bar at the End of the Mini-Cart
add_action( 'woocommerce_widget_shopping_cart_after_buttons', function() {
echo do_shortcode('[fsl-progress-bar]');
});Available Filter Hooks
Our plugin includes many custom filter hooks for internal functionalities, but we won’t cover all of them, as they may not be relevant for regular customization. Instead, we’ll focus on the most important ones that allow for useful modifications.
fsl_min_amount
This filter hook allows you to modify the free shipping threshold. It takes and returns a single parameter, $amount, which represents the free shipping threshold.
- If the filter returns
null, the free shipping progress bar will not appear. - If a custom amount is returned, the progress bar will use that value as the threshold.
This hook can be used in various scenarios, as it allows complete control over when the progress bar appears. It can be used to enable or disable the progress bar based on specific products in the cart, product tags or categories, user roles, shipping zones, specific countries, or any other custom conditions.
Enable Progress Bar Only for Specific Categories
This example ensures that the progress bar appears only if all products in the cart belong to specific categories. If any product in the cart does not belong to the allowed categories, the progress bar will be hidden.
Make sure to modify the slugs inside $allowed_categories to match the actual category slugs used in your store.
add_filter('fsl_min_amount', function ($amount) {
if (!WC()->cart) {
return;
}
// Define the allowed product categories.
$allowed_categories = [
'category_slug',
'another-category-slug',
];
// Loop through each item in the cart.
foreach (WC()->cart->get_cart() as $cart_item_key => $cart_item) {
// Check if the product does not belong to the allowed categories.
if (!has_term($allowed_categories, 'product_cat', $cart_item['product_id'])) {
// Set the amount to null and exit the loop.
$amount = null;
break;
}
}
// Return the final amount (null if any product is not from allowed categories).
return $amount;
});Enable Free Shipping Progress Bar Only for Specific Countries
This example ensures that the progress bar appears only if the customer’s shipping country is Germany (DE) or Sweden (SE). If the customer selects any other country, the progress bar will be hidden.
add_filter('fsl_min_amount', function ($amount) {
$customer = WC()->customer;
$customer_country = 'DE'; // Default fallback country
if ($customer) {
$customer_country = $customer->get_shipping_country();
}
// Allow free shipping only for Germany (DE) and Sweden (SE)
if (!in_array($customer_country, ['DE', 'SE'], true)) {
$amount = null;
}
return $amount;
});Restrict Free Shipping Progress Bar for a Specific User Role
This example hides the progress bar for users with a specific WordPress role. If a logged-in user has the restricted role, the progress bar will not appear.
Modify forbidden_role to match the actual role you want to restrict.
add_filter('fsl_min_amount', function ($amount) {
$role_name = 'forbidden_role';
$user = wp_get_current_user();
if (in_array($role_name, (array) $user->roles)) {
$amount = null;
}
return $amount;
});Exclude Specific Products from Free Shipping Eligibility
This example hides the progress bar if any excluded product is in the cart.
Modify [123, 456] with the actual product IDs you want to exclude.
add_filter('fsl_min_amount', function ($amount) {
if (!WC()->cart) {
return;
}
// Define the product IDs you want to exclude
$excluded_products = [123, 456]; // Replace with actual product IDs
// Check if any excluded product is in the cart
foreach (WC()->cart->get_cart() as $cart_item_key => $cart_item) {
if (in_array($cart_item['product_id'], $excluded_products)) {
// Set the amount to null and exit the loop.
$amount = null;
break;
}
}
// Return the final amount (null if any product is from an excluded products array).
return $amount;
});Exclude Products with Specific Tags from Free Shipping Eligibility
This example hides the progress bar if any product in the cart has a specific product tag.
Modify excluded-tag and no-free-shipping with the actual product tag slugs you want to exclude.
add_filter('fsl_min_amount', function ($amount) {
if (!WC()->cart) {
return;
}
// Define the excluded product tags.
$excluded_tags = [
'excluded-tag',
'no-free-shipping',
];
// Loop through each item in the cart.
foreach (WC()->cart->get_cart() as $cart_item_key => $cart_item) {
// Check if the product has any of the excluded tags.
if (has_term($excluded_tags, 'product_tag', $cart_item['product_id'])) {
// Set the amount to null and exit the loop.
$amount = null;
break;
}
}
// Return the final amount (null if any product has an excluded tag).
return $amount;
});