[![License](https://img.shields.io/badge/license-GPL--2.0%2B-red.svg)](https://github.com/jetixwp/really-simple-free-shipping/blob/master/license.txt)

# 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](#overview)
2. [Installation](#installation)
3. [Basic Configuration](#basic-configuration)
4. [Advanced Settings](#advanced-settings)
5. [Shortcodes](#shortcodes)
6. [Troubleshooting](#troubleshooting)
7. [Developer Guide](#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](https://wordpress.org/plugins/really-simple-free-shipping)
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:
		 ```bash
		 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:
	 ```php
	 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.

```php
apply_filters( 'rs_free_shipping_allowed_html', $tags )
```

**Parameters:**
- `$tags` (array) - Allowed HTML tags and attributes

**Example:**
```php
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.

```php
do_action( 'rs_free_shipping_loaded' )
```

**Example:**
```php
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.

```php
apply_filters( 'rs_free_shipping_settings_tabs_array', $tabs )
```

---

### Helper Functions

#### Check Selected Products in Cart

```php
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:**
```php
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

```php
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:**
```php
use function RS_Free_Shipping\WooCommerce\get_cart_total;

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

---

#### Get Asset Version

```php
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:**
```php
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:

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

- **Documentation:** See this file and the plugin settings pages
- **Issues:** [GitHub Issues](https://github.com/jetixwp/really-simple-free-shipping/issues)
- **Email:** support@jetixwp.com

---