Skip to content
/ really-simple-free-shipping Public

Extends default free shipping workflow of WooCommerce to conditionally apply free shipping on Selected Products, Progress Bars, Shipping Counters and more.

jetixwp.com/plugins/rs-free-shipping-for-woocommerce
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

JetixWP/really-simple-free-shipping

BranchesTags

Repository files navigation

License

Really Simple Free Shipping for WooCommerce - Setup Documentation

Extends default free shipping workflow of WooCommerce to conditionally apply free shipping on Selected Products, Progress Bars, Shipping Counters and more.

📋 Table of Contents

  1. Overview
  2. Installation
  3. Basic Configuration
  4. Advanced Settings
  5. Shortcodes
  6. Troubleshooting
  7. Developer Guide

Overview

Really Simple Free Shipping for WooCommerce is a powerful plugin that extends WooCommerce's default free shipping functionality. It allows you to:

  • ✅ Selected Products Free Shipping - Enable free shipping for specific products or product selections
  • ✅ Progress Indicators - Display visual progress bars and text to customers showing how close they are to qualifying for free shipping
  • ✅ Flexible Calculations - Use multiple calculation methods for cart totals (subtotal, total, contents, with/without discounts and taxes)
  • ✅ Free Shipping with or Without Minimum Cart Value - Apply free shipping with or without minimum cart value requirements
  • ✅ Performance Optimized - Caching and optimized database queries
  • ✅ Shipping Counters - Real-time progress updates as cart changes
  • ✅ Easy to Use - Simple admin interface with clear configuration options

System Requirements

  • WordPress 6.0 or higher
  • PHP 8.0 or higher
  • WooCommerce 7.0 or higher

Installation

Method 1: Via WordPress Plugin Directory

  1. Log in to your WordPress dashboard
  2. Navigate to Plugins > Add New
  3. Search for "Really Simple Free Shipping for WooCommerce"
  4. Click Install Now button
  5. Once installed, click Activate Plugin
  6. You'll see a new menu item: JetixWP > Free Shipping

Method 2: Manual Installation

  1. Download the plugin zip file from WordPress.org
  2. Extract the zip file
  3. Upload the really-simple-free-shipping folder via FTP to /wp-content/plugins/
  4. Go to Plugins in WordPress admin and find "Really Simple Free Shipping for WooCommerce"
  5. Click Activate Plugin

Verification

After activation, verify that:

  • A new menu item "JetixWP" appears in the WordPress sidebar
  • Under "JetixWP", you see "Free Shipping" submenu
  • You can click "Free Shipping" to access the settings page

Basic Configuration

Step 1: Select Products for Free Shipping

  1. Go to JetixWP > Free Shipping

  2. You'll be on the Selected Products tab

  3. Under the "Products" field, select the products that should qualify for free shipping

    • You can search for products by name
    • Multiple products can be selected
    • Use Ctrl/Cmd + Click to select/deselect individual products

  4. Choose a method:

    • Selected Products with Minimum Cart Value: Requires BOTH a selected product in cart AND minimum cart value met
    • Selected Products without Minimum Cart Value: Requires ONLY a selected product in cart

  5. Click Save Changes

Step 2: Create a Shipping Zone (if needed)

  1. Go to WooCommerce > Settings > Shipping > Shipping zones
  2. Click Add Shipping Zone or edit an existing zone
  3. Configure the zone (region/country)
  4. Under "Shipping Methods", click Add Shipping Method
  5. Select "Free Shipping - Selected Products" from the dropdown
  6. Enter a Method Title (e.g., "Free Shipping - Selected Items")
  7. Optionally set a minimum order amount
  8. Save the zone

Step 3: Enable Progress Display (Optional)

To show customers a progress bar or progress text indicating how close they are to free shipping:

Progress Bar

  1. Go to JetixWP > Free Shipping
  2. Click the Progress Bar tab
  3. Check Enable Progress Bar
  4. Optionally check Show Globally to display on all pages (recommended)
  5. Customize colors and messages as desired
  6. Click Save Changes
  7. Add the shortcode [rs_free_shipping_progress_bar] to your shop page, cart page, or sidebar

Progress Text

  1. Go to JetixWP > Free Shipping
  2. Click the Progress Text tab
  3. Check Enable Progress Text
  4. Customize the messages using available placeholders:
    • {goal_counter} - Amount needed to reach free shipping
    • {goal_total} - Total required for free shipping
    • {current_cart_total} - Current cart total
  5. Click Save Changes
  6. Add the shortcode [rs_free_shipping_progress_text] to your site

Advanced Settings

Calculation Tab

The Calculation tab allows you to customize how cart totals are calculated for free shipping eligibility.

Available Options

Option Description Default
Cart Total Method Which cart total to use for calculations Cart Subtotal
Exclude Discounts Remove coupon discounts from the calculation Enabled
Exclude Shipping Remove shipping costs from the calculation Disabled
Exclude Shipping Taxes Remove shipping tax from the calculation Disabled
Manual Min Cart Value Override the shipping zone's minimum with a specific value Disabled

Common Scenarios

Scenario 1: Free shipping only on products totaling $50 (before tax)

  • Cart Total Method: Cart Subtotal
  • Exclude Discounts: ✓ Checked
  • Exclude Shipping: Unchecked
  • Manual Min Cart Value: Set to $50

Scenario 2: Free shipping when products total $100 including everything

  • Cart Total Method: Cart Total
  • Exclude Discounts: Unchecked
  • Exclude Shipping: Unchecked
  • Manual Min Cart Value: Set to $100

Scenario 3: Free shipping when qualifying products reach $75 (after discounts)

  • Cart Total Method: Cart Subtotal
  • Exclude Discounts: Unchecked (to include coupons)
  • Exclude Shipping: Unchecked
  • Manual Min Cart Value: Set to $75

Progress Bar Tab

Customize the appearance and behavior of the progress bar.

Option Description
Enable Progress Bar Show/hide the progress bar functionality
Show Globally Display on all pages (when enabled, shows at bottom of page)
Background Color The background color of the progress bar container
Progress Color The color of the filled portion of the progress bar
Content Color The text color for progress information
Goal Counter Content Message shown when customer hasn't reached free shipping threshold
Free Shipping Available Message shown when free shipping threshold is met

Message Placeholders

In the message fields, use these placeholders:

  • {goal_counter} - Remaining amount needed for free shipping (formatted as currency)
  • {goal_total} - Total amount required for free shipping (formatted as currency)
  • {current_cart_total} - Current cart total (formatted as currency)
  • {progress_bar} - Embed the progress bar itself (for Progress Text messages)

Example Messages:

Goal Counter: "Spend {goal_counter} more for FREE SHIPPING!" Free Shipping Available: "Congrats! You've unlocked FREE SHIPPING!"

Progress Text Tab

Configure text-based progress notifications.

Option Description
Enable Progress Text Show/hide the progress text functionality
Show When Goal Reached Display text even after free shipping is achieved
Goal Counter Content Message when working toward free shipping threshold
Free Shipping Available Message when threshold is met

Shortcodes

[rs_free_shipping_progress_bar]

Displays a visual progress bar showing free shipping progress.

Basic Usage:

[rs_free_shipping_progress_bar]

With Custom Classes:

[rs_free_shipping_progress_bar additional_classes="my-custom-class"]

With Custom Messages:

[rs_free_shipping_progress_bar
	goal_counter_content="Add {goal_counter} more to your cart for free shipping"
	free_shipping_available_content="Free shipping is yours!"]

Parameters:

  • additional_classes (string) - CSS classes to add to the progress bar container
  • goal_counter_content (string) - Custom message for the progress state
  • free_shipping_available_content (string) - Custom message when free shipping is available

Output: A visual progress bar with current progress percentage and customizable messages.

[rs_free_shipping_progress_text]

Displays text-based progress updates about free shipping eligibility.

Basic Usage:

[rs_free_shipping_progress_text]

With Custom Messages:

[rs_free_shipping_progress_text
	goal_counter_content="Get {goal_counter} more in products to qualify for free shipping"
	free_shipping_available_content="You qualify for FREE SHIPPING!"]

Parameters:

  • goal_counter_content (string) - Template for progress state messages
  • free_shipping_available_content (string) - Template for free shipping achieved message

Output: Text message showing free shipping progress.

[rs_free_shipping_mini_progress_bar]

Displays a compact version of the progress bar (same as [rs_free_shipping_progress_bar] but optimized for sidebars/widgets).

Usage:

[rs_free_shipping_mini_progress_bar]

Output: A compact progress bar suitable for sidebars.

Common Configurations

Configuration 1: Simple Free Shipping on Specific Products

Goal: Give customers free shipping if they buy specific high-margin products (e.g., a "Free Shipping" bundle product).

Steps:

  1. Select Products tab → Select the bundle product
  2. Method: "Selected Products without Minimum Cart Value"
  3. Create/edit shipping zone → Add "Free Shipping - Selected Products" method
  4. Don't set a minimum order amount
  5. Save

Result: Any customer with that product in cart gets free shipping.

Configuration 2: Free Shipping on $75+ Orders (Specific Products)

Goal: Free shipping when qualifying products total $75 or more.

Steps:

  1. Selected Products tab → Select qualifying products
  2. Method: "Selected Products with Minimum Cart Value"
  3. Calculation tab → Manual Min Cart Value: $75
  4. Create/edit shipping zone → Add "Free Shipping - Selected Products" method
  5. Set minimum order amount: $75
  6. Save

Result: Free shipping when selected products total at least $75.

Configuration 3: Free Shipping Progress Display

Goal: Show customers a progress bar and message indicating how close they are to free shipping.

Steps:

  1. Configure Selected Products and Calculation as desired
  2. Progress Bar tab:
    • Enable Progress Bar ✓
    • Show Globally ✓
    • Customize colors
    • Set messages
  3. Progress Text tab:
    • Enable Progress Text ✓
    • Set messages using placeholders
  4. Add shortcodes to cart/shop pages: 
    [rs_free_shipping_progress_bar]
[rs_free_shipping_progress_text]
  5. Save changes

Result: Customers see real-time progress toward free shipping threshold.

Troubleshooting

Free Shipping Not Working

Problem: Free shipping isn't being offered even when conditions should be met.

Solution:

  1. Verify the shipping zone is created and active
  2. Confirm "Free Shipping - Selected Products" is added to the zone
  3. Check that products are selected in the plugin settings
  4. Verify the calculation method and minimum cart value settings
  5. Test with a new customer session (clear cart and cookies)
  6. Check WooCommerce shipping zone priority (zones higher in the list take precedence)

Progress Bar/Text Not Showing

Problem: Shortcodes aren't displaying the progress bar or progress text.

Solution:

  1. Verify the shortcode is enabled:
    • Progress Bar tab → "Enable Progress Bar" ✓
    • Progress Text tab → "Enable Progress Text" ✓
  2. Confirm shortcode is placed on the correct page (cart, shop, or global)
  3. Check that you have selected products in the settings
  4. Clear page cache if using a caching plugin
  5. Verify that JavaScript is not being blocked (check browser console for errors)

Products Not Appearing in Select Box

Problem: Products don't appear in the product selector dropdown.

Solution:

  1. Ensure products are published and active
  2. Check product visibility settings (not hidden)
  3. Clear the products cache:
    • Go to database or use WP CLI: 
      wp transient delete rs_free_shipping_products_cache_full
  4. Refresh the page
  5. If you have 10k+ products, the list may be paginated (use search)

Incorrect Cart Totals

Problem: Free shipping isn't being applied when it should be, or is applied when it shouldn't.

Solution:

  1. Go to Calculation tab
  2. Review the "Cart Total Method" selection:
    • Try different options (Subtotal vs Total vs Contents Total)
  3. Check "Exclude Discounts" / "Exclude Shipping" settings
  4. Verify "Manual Min Cart Value" is set correctly
  5. Test with simple products (non-variable, non-bundle) first
  6. Check if tax settings affect the calculation

Performance Issues

Problem: Admin pages are slow or site performance degraded after plugin activation.

Solution:

  1. The plugin caches product lists (6-hour expiry)
  2. If you have 100k+ products, search in the product selector instead of scrolling
  3. Enable debug mode only during development: 
    define( 'JETIXWP_DEBUG', true );
  4. Check server logs for errors
  5. Disable other caching plugins temporarily to test

Developer Guide

Hooks & Filters

Filter: rs_free_shipping_allowed_html

Filters the HTML tags allowed in progress bar/text output.

apply_filters( 'rs_free_shipping_allowed_html', $tags )

Parameters:

  • $tags (array) - Allowed HTML tags and attributes

Example:

add_filter( 'rs_free_shipping_allowed_html', function( $tags ) {
		// Add custom tags
		$tags['button'] = array(
				'class' => true,
				'id' => true,
		);
		return $tags;
});

Action: rs_free_shipping_loaded

Fires when the plugin has fully loaded and initialized.

do_action( 'rs_free_shipping_loaded' )

Example:

add_action( 'rs_free_shipping_loaded', function() {
		// Your custom code here
		error_log( 'Really Simple Free Shipping loaded' );
});

Filter: rs_free_shipping_settings_tabs_array

Filter available settings tabs in the admin interface.

apply_filters( 'rs_free_shipping_settings_tabs_array', $tabs )

Helper Functions

Check Selected Products in Cart

namespace RS_Free_Shipping\WooCommerce;

has_selected_products_in_cart_contents( $cart_contents, $selected_product_ids )

Parameters:

  • $cart_contents (array) - Cart items array
  • $selected_product_ids (array) - Product IDs to check for

Returns: (bool) True if any selected product is in cart, false otherwise

Example:

use function RS_Free_Shipping\WooCommerce\has_selected_products_in_cart_contents;

$cart = WC()->cart->get_cart();
$selected_ids = get_option( 'selected_products', array() );

if ( has_selected_products_in_cart_contents( $cart, $selected_ids ) ) {
		echo 'Cart has a selected product!';
}

Get Cart Total

namespace RS_Free_Shipping\WooCommerce;

get_cart_total( $calculation_method = 'cart_total' )

Parameters:

  • $calculation_method (string) - One of: cart_total, cart_subtotal, cart_contents_total

Returns: (float) Calculated cart total

Example:

use function RS_Free_Shipping\WooCommerce\get_cart_total;

$subtotal = get_cart_total( 'cart_subtotal' );
echo 'Cart subtotal: ' . wc_price( $subtotal );

Get Asset Version

namespace RS_Free_Shipping;

get_asset_version( $file_path = '' )

Parameters:

  • $file_path (string) - Full path to asset file (optional)

Returns: (string|int) Plugin version or file modification time

Description: Returns file modification time when JETIXWP_DEBUG is enabled, otherwise returns plugin version constant.

Example:

use function RS_Free_Shipping\get_asset_version;

wp_enqueue_script(
		'my-script',
		plugins_url( 'my-script.js', __FILE__ ),
		array(),
		get_asset_version( __DIR__ . '/my-script.js' )
);

Debug Mode

Enable debug mode for development and troubleshooting:

define( 'JETIXWP_DEBUG', true );

What Changes in Debug Mode:

  • Asset versioning uses file modification times (no caching)
  • Product list cache is bypassed
  • Stricter error reporting
  • Additional logging information

When to Use:

  • During development
  • When troubleshooting issues
  • When making changes to CSS/JS files

Support

About

Extends default free shipping workflow of WooCommerce to conditionally apply free shipping on Selected Products, Progress Bars, Shipping Counters and more.

jetixwp.com/plugins/rs-free-shipping-for-woocommerce

Topics

wordpress wordpress-plugin

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases 1

1.0.1 Latest
Dec 8, 2025

Languages