WPCalibrate Shipping Rules for WooCommerce

An enterprise-grade, high-performance conditional shipping rates and methods engine for WooCommerce. Define dynamic shipping prices, surcharges, discounts, custom delivery labels, and method availability rules through an intuitive visual interface without writing code.

Table of Contents

• About
• Key Features
• Calculation Models
• Condition Library
• Action Outcomes
• Documentation & Usage Guide
  • 1. Creating Rules
  • 2. Testing with Simulator & Debugger
  • 3. Loading Built-in Demo Data
  • 4. Priority & Conflict Resolution
• Installation
• Updating via WordPress Dashboard
• Compatibility
• Changelog
• Support & Contributing
• License

About

WPCalibrate Shipping Rules gives WooCommerce store owners complete granular control over checkout shipping calculations. Whether offering free shipping above a threshold for specific countries, adding heavy freight surcharges, granting VIP member discounts, calculating tiered item shipping, or hiding local pickup for oversized products, WPCalibrate executes complex rule evaluations deterministically in sub-millisecond execution times.

The plugin stores rules in a dedicated, indexed database table ({$wpdb->prefix}wpcalibrate_shipping_rules) rather than cluttering wp_posts and wp_postmeta, providing maximum checkout performance even with hundreds of rules.

Key Features

• Visual Condition Builder: Create multi-group nested condition trees using intuitive AND/OR logic.
• 9 Flexible Rate Calculation Models: From flat rates and percentage fees to complex tiered weight/item steps with cost floors and ceilings.
• Cross-Method Actions: Apply surcharges or percentage discounts to existing shipping methods (e.g. flat_rate:1), rename methods dynamically, or hide methods when conditions are met.
• Shipping Rule Simulator & Debugger: Validate your configuration against customer destinations, subtotals, weights, and items before going live. Displays a complete step-by-step diagnostic audit log.
• One-Click Demo Data: Load 6 pre-configured, real-world shipping scenarios (Free Shipping, Freight Surcharge, VIP Discount, California Express, Tiered Item Rate, and Restricted Pickup) for instant testing.
• High-Performance Order Storage (HPOS): Native declaration and full support for WooCommerce HPOS custom order tables (custom_order_tables).
• Cart & Checkout Blocks Ready: 100% compatible with modern WooCommerce Gutenberg Cart & Checkout Blocks as well as classic shortcode checkouts.
• Multiple Shipping Packages: Normalizes calculations per shipping package to ensure package-accurate shipping charges when items ship from separate locations.
• Safe JSON Import & Export: Backup and migrate your rules between staging and production with built-in format validation and collision safety.
• Non-Destructive by Default: Protects your business data during plugin updates or deactivations. Data is only deleted on uninstall if explicitly enabled in Settings.

Calculation Models

WPCalibrate includes 9 native calculation algorithms powered by RateCalculator:

Condition Library

WPCalibrate supports 20 modular evaluators that can be combined across multiple condition groups:

1. Geographic & Destination

• Country: Target specific destination countries (e.g., US, GB, CA).
• State / Province: Filter by state or region code (e.g., CA, NY, TX).
• Postcode / ZIP: Supports exact codes (90210), wildcard patterns (902*), and numeric ranges (90200...90250).
• Shipping Zone: Match against WooCommerce native shipping zones.

2. Cart Totals & Measurements

• Subtotal: Cart subtotal amount.
• Subtotal Before Coupons: Pre-discount merchandise total.
• Subtotal After Coupons: Final discounted merchandise total.
• Total Weight: Combined weight of package items (kg/lbs).
• Item Quantity: Total quantity of physical items.
• Distinct Products Count: Number of unique product line items.
• Dimensions / Volume: Package volumetric sizing.

3. Catalog & Products

• Specific Products: Filter by specific product IDs.
• Product Categories: Match against product taxonomies.
• Product Tags: Match based on product tags.
• Shipping Classes: Check for assigned WooCommerce shipping classes.
• Physical vs Virtual: Differentiate between physical goods and downloadable/service items.

4. Customer & Context

• Customer Role: Target user groups (e.g., wholesale_customer, vip, subscriber).
• Customer Type: Differentiate between Guest (unregistered) and Logged-In accounts.
• Applied Coupon: Check if a promotional coupon code is currently active in the cart.
• Day of Week: Apply time-sensitive shipping rules based on checkout day (e.g., Weekend delivery rates).

Action Outcomes

When a rule's conditions evaluate to true, WPCalibrate can trigger one or more outcomes:

1. Add Custom Rate: Injects a new shipping rate with custom label, cost model, tax status, and estimated delivery window (e.g., Next-Day Express (1-2 business days)).
2. Apply Surcharge: Adds a fixed or percentage surcharge to existing shipping methods (e.g., add $15 to standard ground for heavy freight).
3. Apply Discount: Deducts a fixed amount or percentage from matching rates (e.g., 15% off for VIP members).
4. Set Cost to Free ($0): Overrides matching method costs to free shipping.
5. Hide Shipping Methods: Hides specified shipping methods (e.g., hide Local Pickup for oversized products).
6. Allow Only Selected Methods: Restricts the checkout to show exclusively the designated methods.
7. Rename Method: Changes the customer-facing label of an existing shipping method.
8. Add Delivery Estimate: Appends delivery timing labels (e.g., Est. Delivery: 2-3 Days).

Documentation & Usage Guide

1. Creating Rules

1. Navigate to WPCalibrate > Shipping Rules > Rule Builder.
2. Enter a Rule Name and optional internal description notes.
3. Under Conditions & Rules Logic, select how multiple condition groups combine (AND vs OR).
4. Add conditions within groups, choosing your criteria, comparison operator, and target values.
5. Under Shipping Rates & Action Outcomes, select your action type. The builder automatically shows only the relevant configuration fields for your selected outcome.
6. Set the Evaluation Priority (lower numbers execute first, e.g. 10, 20, 30).
7. Optionally enable Stop Processing if you want matching orders to halt evaluation of lower-priority rules.
8. Click Save Rule.

2. Testing with Simulator & Debugger

Before testing on a live storefront:

1. Open the Simulator & Debugger tab.
2. In the left panel, specify test parameters:
   • Destination Country, State, Postcode.
   • Cart Subtotal, Weight, Item Quantity.
   • Customer Role, Active Coupon, and Day of Week.
3. Click Run Shipping Simulation.
4. Inspect the Simulation Outcomes card to view the final generated rates and method IDs.
5. Review the Step-by-Step Rule Evaluation Log below, showing each rule in priority order with color-coded pass/fail indicators and individual condition breakdowns.

3. Loading Built-in Demo Data

To quickly explore the engine with real-world examples:

1. Go to WPCalibrate > Shipping Rules > Rules.
2. Click the Load Demo Rules button in the header toolbar.
3. The plugin will non-destructively seed 6 production-grade sample rules into your database.

Installation

From WordPress Dashboard:

1. Download wpcalibrate-shipping-rules-1.0.0.zip from the latest GitHub Release.
2. In your WordPress admin, go to Plugins > Add New > Upload Plugin.
3. Choose the downloaded ZIP file and click Install Now.
4. Click Activate Plugin.
5. Access the plugin via the WPCalibrate > Shipping Rules menu in the sidebar.

Via FTP / Manual:

1. Extract wpcalibrate-shipping-rules-1.0.0.zip.
2. Upload the wpcalibrate-shipping-rules folder to /wp-content/plugins/.
3. Activate the plugin via Plugins > Installed Plugins.

Updating via WordPress Dashboard

This repository is structured for compatibility with standard WordPress GitHub updaters (such as Git Updater):

1. Install and activate the Git Updater plugin.
2. Add this repository URI: https://github.com/zeeshanraza-official/wpcalibrate-shipping-rules.
3. Future updates and release tags will appear automatically under Dashboard > Updates and Plugins.

Compatibility

• WordPress: 6.8+ (Tested up to 7.1.3)
• WooCommerce: 9.0+ (Tested up to 11.2.1)
• PHP: 8.2 or newer (Tested up to PHP 8.3)
• Database: MySQL 5.7+ / MariaDB 10.3+
• Architectures: High-Performance Order Storage (HPOS), Gutenberg Cart & Checkout Blocks, Classic Shortcode Checkout, Multi-Package Shipping.

Changelog

[1.0.4] - 2026-10-15

• Fixed: Simulator "Final Generated Shipping Rates" method ID layout. Implemented structured .wpcalibrate-rate-id-badge with dedicated labels and word-break: break-all; overflow-wrap: anywhere; container.
• Fixed: Simulator card header layout collisions where titles and descriptions were forced side-by-side. Added .wpcalibrate-card-title-group.
• Improved: Expanded rate cards grid min-width from 240px to 280px with subtle hover feedback.
• Added: Polished styling for .wpcalibrate-zone-pill and .wpcalibrate-sim-meta-item.

[1.0.3] - 2026-10-15

• Fixed: Class import resolution in RuleListPage.php when loading demo data.
• Fixed: Standardized demo condition type product_shipping_class to shipping_class.
• Improved: Payload optimization with native PHP arrays and defensive try ... catch (\Throwable) exception boundary with admin notices.
• Added: Automated demo data installation unit tests (58/58 passed).

[1.0.2] - 2026-10-15

• Fixed: Context-aware dynamic field visibility in Rule Builder preventing squished action inputs.
• Improved: Redesigned table row action buttons into polished 32x32px rounded icon controls with semantic hover states and tooltips.
• Added: Built-in Demo Data provider (DemoData.php) with 6 pre-configured shipping scenarios.

[1.0.1] - 2026-10-15

• Fixed: Constrained admin sidebar menu logo icon to strict 20x20px with standard WordPress dashboard opacity (0.72 -> 1.0 hover/active).
• Added: Dedicated Overview & Documentation tab (OverviewPage.php) with Plugin Purpose, How-to-Use Guide, and Method Architecture.

[1.0.0] - 2026-10-15

• Initial Release: Core rules engine, 20 condition evaluators, 9 rate calculation models, Simulator & Debugger, and HPOS/Blocks compatibility declarations.

Support & Contributing

• Website: wpcalibrate.com
• Email: support@wpcalibrate.com
• Issues: Please report bugs or submit feature requests through GitHub Issues.

License

WPCalibrate Shipping Rules is licensed under the GNU General Public License v2.0 or later. Copyright © 2026 WPCalibrate. All rights reserved.