Free Shipping and Progressbar PRO

Technical documentation for the WooCommerce plugin Free Shipping and Progressbar PRO.

Current plugin version: 2.1.1

Purpose

This plugin adds a sticky free shipping and upsell bar to a WooCommerce storefront.

The plugin has two related frontend responsibilities:

• Show a free shipping progress message only when the current shipping zone has a free shipping threshold.
• Show an upsell product carousel whenever there are products in the cart, independent of the free shipping threshold.

The plugin also adds a WooCommerce admin page where upsell rules can be managed without editing code.

Main Features

• Free shipping progress bar based on the detected WooCommerce shipping zone.
• Support for native WooCommerce free shipping methods.
• Support for Weight Based Shipping / WBSNG-style rule configuration.
• Smart upsells based on source categories, target categories, source products, and target products.
• Product-based upsell rules.
• Category-to-category upsell rules.
• Rule priorities.
• Fallback upsells when no rule-based upsell products are found.
• Product and variation filtering for stock, price, WCPOS POS-only visibility, and gift card products.
• WooCommerce Cart and Checkout Blocks support.
• Classic WooCommerce cart and checkout fallback support.
• Sydney theme cart counter synchronization.
• WPML-aware product and category ID translation.
• Admin-managed import/export for upsell rules.
• Admin product search with token matching and search aliases.
• Admin autocomplete fields that automatically add the selected product's categories to the same rule panel.
• Desktop carousel autoplay with an admin-managed interval.
• Shortened variation names in the frontend carousel.

Requirements

• WordPress with WooCommerce active.
• PHP 8.3 compatible codebase.
• WooCommerce Cart and Checkout Blocks are supported.
• Classic WooCommerce cart and checkout are still supported.
• WPML is supported when present, but the plugin also works without WPML.

Installation

Upload the plugin folder or zip so WordPress sees this structure:

wp-content/plugins/free-shipping-and-progressbar-pro/
    free-shipping-and-progressbar-pro.php
    includes/
        free-shipping-bar.php
        admin/
            menu.php
            settings.php
    README.md

Activate Free Shipping and Progressbar PRO in WordPress Admin > Plugins.

File Structure

free-shipping-and-progressbar-pro.php

Main plugin bootstrap. It checks for WooCommerce and loads the admin and frontend modules.

includes/free-shipping-bar.php

Main frontend and WooCommerce integration file. It contains shipping zone detection, upsell selection, frontend CSS/JS output, AJAX endpoints, add-to-cart handling, Blocks compatibility, and Store API shipping adjustments.

includes/admin/menu.php

Registers the WooCommerce submenu page for the plugin settings.

includes/admin/settings.php

Renders and saves the admin settings page. It handles upsell rules, product/category selectors, product search AJAX, import/export, debug mode, WPML source language setting, and carousel autoplay interval.

assets/js/

Historical asset files from the external JavaScript refactor. The stable frontend implementation currently lives inline in includes/free-shipping-bar.php.

WordPress Hooks

The plugin uses these important WordPress and WooCommerce hooks:

• plugins_loaded: initializes the plugin after WooCommerce is available.
• admin_menu: adds the settings page below WooCommerce.
• admin_enqueue_scripts: loads SelectWoo/Select2 assets for the admin rule editor.
• wp_footer: outputs frontend configuration, CSS, and JavaScript.
• wp_enqueue_scripts: patches a known WooCommerce Blocks dependency warning for the Mollie/Inpsyde handle when possible.
• wp_ajax_get_free_shipping_progress: authenticated free shipping and upsell AJAX endpoint.
• wp_ajax_nopriv_get_free_shipping_progress: guest free shipping and upsell AJAX endpoint.
• wp_ajax_free_shipment_progressbar_add_upsell_to_cart: authenticated add-to-cart endpoint for carousel products.
• wp_ajax_nopriv_free_shipment_progressbar_add_upsell_to_cart: guest add-to-cart endpoint for carousel products.
• wp_ajax_free_shipment_progressbar_search_products: admin product search endpoint.
• woocommerce_package_rates: forces WBSNG shipping rates to free when the free shipping threshold is reached.
• woocommerce_store_api_cart_shipping_rates: adjusts Store API shipping rates for WooCommerce Blocks.

Stored Options

The plugin stores settings in the WordPress options table:

free_shipment_progressbar_debug

yes or no. Enables debug logging in browser console and selected PHP logging.

free_shipment_progressbar_wpml_source_language

Currently forced to en from the settings page so WPML treats the plugin strings and rule storage as English-source content. Admin product selectors still follow the requested product language, such as lang=nl, lang=it, or any other WPML product language.

free_shipment_progressbar_upsell_rules

Array of admin-managed upsell rules.

free_shipment_progressbar_carousel_interval

Autoplay interval for the desktop upsell carousel, in seconds. Default is 30. Set to 0 to disable autoplay. Values above 300 are capped.

Upsell Rule Data Model

Each upsell rule has this structure:

[
    'enabled' => true,
    'priority' => 100,
    'source_categories' => [59],
    'target_categories' => [1880, 35],
    'source_products' => [],
    'target_products' => [],
]

Rule behavior:

• A rule matches when at least one source category or source product is in the cart.
• Matching rules contribute target categories and target products.
• Higher priority rules are shown first.
• Product IDs and category IDs are normalized to integers.
• WPML object IDs are translated to the current frontend language where possible.
• If no matching products are found, the plugin falls back to random sellable online products.

Admin Rule Editor

The admin page is located under WooCommerce.

The editor supports:

• Adding new rules.
• Removing rules.
• Enabling/disabling rules.
• Setting priority.
• Selecting source categories.
• Selecting target categories.
• Searching and selecting source products.
• Searching and selecting target products.
• Importing/exporting rule JSON.
• Resetting default rules.
• Setting carousel autoplay interval.

Product selection behavior:

• Product search uses a custom AJAX endpoint.
• Every typed token must match product title, slug, or SKU.
• Additional aliases help searches such as cap lang find products like Cap Lang Kayu Putih.
• When a product is selected, its categories are automatically selected in the same source or target panel.
• Selected products and categories can be removed from the selector.

Frontend Flow

On page load, the plugin:

1. Outputs the fsb_ajax configuration object in the footer.
2. Detects whether the current cart has products.
3. Reads the best available shipping address:
   • WooCommerce Blocks cart/checkout address.
   • Classic WooCommerce address fields.
   • Logged-in customer account address on account pages.
   • Customer city fallback where appropriate.
4. Calls get_free_shipping_progress through admin-ajax.php.
5. Receives progress data, shipping zone data, cart count, and upsells.
6. Renders the sticky bar when upsells or free shipping progress are available.
7. Keeps the Sydney cart counter synchronized with WooCommerce cart updates.

The free shipping progress section is shown only when a free shipping threshold exists for the detected zone.

The upsell carousel is shown when the cart contains products and upsell products are available.

Shipping Zone Detection

The central function is:

free_shipment_progressbar_get_shipping_data($package = [])

It:

• Loads WooCommerce cart if needed.
• Builds a package destination.
• Uses wc_get_shipping_zone() to detect the zone.
• Reads enabled native free_shipping methods.
• Reads enabled WBSNG methods and their rule configuration.
• Returns the lowest free shipping threshold found.

Shipping Savings Calculation

The function:

free_shipment_progressbar_get_shipping_saving_amount($package = [])

calculates the lowest paid shipping amount for the detected package using WooCommerce calculated shipping rates. The returned amount includes shipping tax, because the configured shipping method prices are usually stored excluding tax.

The progress message can therefore show:

Add € X for free shipping and save € Y

On mobile, the shorter message is:

€ X left for free shipping. Save € Y

Product Carousel

The carousel receives products from free_shipment_progressbar_get_upsells().

Products are filtered before display:

• Must exist.
• Must be in stock.
• Must have a price above 0.01.
• Must not be WCPOS POS-only.
• Must not already be in the cart.

Variable products:

• Variable products are expanded to their variations.
• The add-to-cart button uses the variation product ID.
• The frontend name is shortened for readability.

Variation title normalization:

ABC zoete sojasaus (275 ml / 600 ml) - 600 ml

is displayed as:

ABC zoete sojasaus (600 ml)

This only changes the displayed title in the carousel. It does not change product IDs, cart behavior, or WooCommerce product data.

Autoplay:

• Desktop carousel advances automatically.
• Default interval is 30 seconds.
• The interval is configurable in the admin page.
• The previous and next buttons still work manually.
• Mobile remains swipe/scroll based.

WooCommerce Blocks Support

The plugin supports WooCommerce Cart and Checkout Blocks by:

• Reading cart data through wp.data.select('wc/store/cart') when available.
• Invalidating the Store API cart resolution after add-to-cart actions.
• Listening for Store API cart changes.
• Supporting Blocks shipping method changes.
• Adjusting Store API shipping rate output through woocommerce_store_api_cart_shipping_rates.

Defensive checks are used before accessing Blocks data so the plugin does not crash when Blocks are unavailable.

Classic WooCommerce Support

The plugin keeps compatibility with classic WooCommerce pages by:

• Listening to classic WooCommerce jQuery events such as added_to_cart, removed_from_cart, updated_cart_totals, updated_wc_div, and updated_checkout.
• Refreshing WooCommerce fragments after carousel add-to-cart.
• Falling back to classic address fields such as billing and shipping postcode/city/country fields.

Sydney Theme Integration

The plugin includes specific cart counter synchronization for the Sydney/Sydney Pro header:

• Updates .cart-count .count.
• Updates .cart-count .count-number.
• Creates a badge when the wrapper exists but the badge is missing.
• Forces zero when the cart is empty.
• Avoids unstable repeated updates where possible.

WPML Behavior

The admin settings force the source language for plugin strings and stored rule IDs to English:

en

Rules are stored against source-language IDs. On the frontend, category and product IDs are translated to the current language with WPML filters when WPML is available.

Admin product selectors are language-independent. They read the requested product language from the admin request, for example lang=nl or lang=it, and only return products whose WPML product language matches that requested language. This keeps the plugin usable on shops where the WPML interface/source language differs from the product catalog language.

From version 1.2.0.24, existing WPML String Translation records for the free_shipment_progressbar text domain are synchronized to English (en) as source language in the WordPress admin. This prevents WPML from continuing to treat the plugin strings as Dutch source strings after scanning.

WCPOS Visibility

The plugin checks POS-only visibility before showing upsell products.

It reads:

• Legacy _pos_visibility post meta.
• woocommerce_pos_settings_visibility from the options table.

Products or variations marked POS-only are excluded from frontend upsells.

Gift Card Behavior

From version 2.1.0, gift cards are excluded from all free-shipping threshold logic.

The plugin supports WPC Gift Cards for WooCommerce by detecting gift-card style product types and common gift-card metadata. Gift cards are:

• excluded from the amount required for free shipping;
• excluded from the progress-bar percentage;
• excluded from source products and source categories for upsell matching;
• excluded from frontend upsell products;
• excluded from admin upsell product search results;
• unable to trigger the free shipping bar when the cart contains only gift cards.

The normal WooCommerce cart counter still shows the real cart quantity, including gift cards. Only the free-shipping and upsell logic excludes them.

Security Notes

The plugin uses these protections:

• Capability check manage_woocommerce for the admin settings page.
• Nonce check for settings saves.
• Nonce check for write actions such as add-to-cart.
• Product and category IDs are normalized with absint.
• Admin product search is restricted to WooCommerce managers.
• Frontend output is escaped in JavaScript before insertion.
• Product prices are generated through WooCommerce formatting.
• The free shipping progress endpoint is read-only tolerant to avoid stale cached nonce failures.