WPCalibrate Smart Price Rules for WooCommerce

Automated, predictable, and 100% reversible dynamic pricing engine for WooCommerce. Schedule flash sales, apply inventory-based pricing, configure quantity tiers in cart, and enforce strict profit margin protections — without ever permanently mutating or corrupting merchant catalog base prices.

---

Table of Contents

• About
  • Core Philosophy: 100% Reversibility
  • Architecture & Standards
• Features
• Documentation
  • System Requirements
  • Installation
  • Configuration & How to Use
  • Deterministic Conflict Resolution
  • Calculation Methods
  • Condition Triggers
  • Price Preview Simulator
  • In-Dashboard GitHub Auto-Updates
• Developer Hooks & Filters
• Changelog
• License & Support

---

About

WPCalibrate Smart Price Rules provides high-performance pricing automation designed specifically for high-volume WooCommerce stores. Many existing pricing plugins permanently overwrite product prices in the WordPress database (_price, _regular_price), causing catastrophic compounding discounts, cart inaccuracies, or lost baseline catalog data when rules are disabled.

Smart Price Rules takes a clean, mathematical approach:

Core Philosophy: 100% Reversibility

1. Pristine Catalog Base Prices: Base merchant prices in the database are never altered. Effective prices are computed dynamically at runtime using native WooCommerce filters (woocommerce_product_get_price, woocommerce_product_get_sale_price, woocommerce_before_calculate_totals).
2. Instant Rollback: Deactivating a rule or the plugin instantly restores your standard catalog prices with zero residual artifacts or data corruption.
3. No Cart Compounding: In CartPriceHooks, dynamic pricing is always calculated against the product's pristine base catalog price. Recalculating cart totals (e.g. from coupon applications or shipping address updates) never causes accidental recursive discounts.

Architecture & Standards

• PSR-4 Autoloading: Clean namespace WPCalibrate\SmartPriceRules\ with zero legacy global function clutter.
• Strict Typing: declare(strict_types=1); across all classes with PHP 8.2 and 8.3 compatibility.
• WooCommerce HPOS: Full native High-Performance Order Storage (custom_order_tables) compatibility declared.
• Cart & Checkout Blocks: Full support for modern block-based cart and checkout workflows (cart_checkout_blocks).
• Database Normalization: Normalized 3-table relational schema (wpcalibrate_price_rules, wpcalibrate_price_rule_targets, wpcalibrate_price_history) created via WordPress dbDelta().

---

Features

• Deterministic Single-Winner Resolution: When multiple pricing rules match the same product, a single winning rule is selected with predictable tie-breakers. Stacking conflicts and unexpected discounts are eliminated.
• Multi-Target Scope:
  • Entire store catalog (All Products in Store)
  • Specific products
  • Specific product categories (hierarchical term lookups)
  • Specific product tags
  • Individual variable product variations
• Dynamic Condition Triggers:
  • Always (Unconditional): Continuous execution.
  • Schedule Window: Date and time boundaries evaluated against the store's configured local timezone (wp_timezone()).
  • Stock Quantity: Trigger discounts or scarcity pricing based on current inventory thresholds (<, <=, =, >=, >, between).
  • Cart Item Quantity: Volume tiers applied cleanly in cart and checkout.
  • Total Sales Count: Promotional incentives for popular or slow-moving catalog items.
• 5 Price Adjustment Types:
  • Percentage Discount / Decrease (-%)
  • Percentage Markup / Increase (+%)
  • Fixed Amount Decrease (-$)
  • Fixed Amount Increase (+$)
  • Fixed Final Price Override ($)
• Strict Profit Margin Safeguards (Price Guard):
  • Minimum Price Floor: Protects profit margins by ensuring effective price never drops below a merchant-defined floor.
  • Maximum Price Ceiling: Prevents runaway markups.
  • Absolute Floor at 0.0: Guarantees prices never drop below zero.
• Interactive Price Simulator (Price Preview):
  • Test pricing rules on any store product before launching live.
  • Real-time diagnostic audit detailing base price, all matching rules, condition evaluations, the deterministic winner, and margin clamp status.
• Full History & Audit Trail:
  • Automated logging of calculation events, price changes, and rule modifications for audit compliance.
• Native In-Dashboard GitHub Updates:
  • Automatic update checks against the official GitHub releases repository directly in WordPress > Plugins, allowing 1-click updates.

---

Documentation

System Requirements

Requirement	Minimum	Recommended
PHP	8.2	8.2 or 8.3
WordPress	6.5	6.7+
WooCommerce	9.0	9.5+
MySQL / MariaDB	5.7+ / 10.3+	8.0+ / 10.5+

Installation

Option 1: WordPress Dashboard (Recommended)

1. Download the latest wpcalibrate-smart-price-rules-1.0.0.zip from the GitHub Releases page.
2. In your WordPress admin, navigate to Plugins > Add New Plugin > Upload Plugin.
3. Choose the ZIP file and click Install Now.
4. Click Activate Plugin.

Option 2: Manual FTP Upload

1. Extract wpcalibrate-smart-price-rules-1.0.0.zip.
2. Upload the wpcalibrate-smart-price-rules/ folder to your server directory /wp-content/plugins/.
3. Activate the plugin via WordPress > Plugins.

---

Configuration & How to Use

1. Navigate to WPCalibrate > Smart Price Rules in your WordPress admin menu.
2. The Overview tab provides quick shortcuts, architecture guidance, and setup walkthroughs.
3. Click Add New Pricing Rule (or open the Add/Edit Rule tab).
4. Fill in the 4 configuration cards:
   • 1. Rule Information & Status: Give your rule an identifiable name, select Active, and specify an evaluation priority (default: 10).
   • 2. Target Scope: Choose whether the rule targets all products, specific products, categories, tags, or variations.
   • 3. Dynamic Conditions & Schedule: Set your trigger condition (e.g., Stock Quantity <= 10, or a scheduled holiday sale window).
   • 4. Price Adjustment & Margin Safeguards: Choose the adjustment type (e.g. 20% Discount), enter the adjustment value, and set an optional price floor.
5. Click Save and Activate Rule.
6. Switch to the Price Preview tab to test and verify the rule on any product with live conflict explanations.

---

Deterministic Conflict Resolution

When a product qualifies for multiple active pricing rules simultaneously, Smart Price Rules determines exactly one winning rule using this strict evaluation hierarchy:

Step 1: Priority Value (Highest numerical priority wins: Priority 50 beats Priority 10)
   ↓ (if identical priority)
Step 2: Last Updated Timestamp (Most recently saved/modified rule wins)
   ↓ (if identical timestamp)
Step 3: Rule ID (Lowest database ID wins as a stable final tie-breaker)

No conflicting compound discounts are ever created, ensuring predictable margins for store owners.

---

Calculation Methods

Method	Formula	Example ($100 Base)	Guard Behavior
Percentage Decrease	Price = Base - (Base * Rate / 100)	15% off = $85.00	Clamped if below minimum_price
Percentage Increase	Price = Base + (Base * Rate / 100)	10% markup = $110.00	Clamped if above maximum_price
Fixed Decrease	Price = Base - Fixed Amount	$20.00 off = $80.00	Strictly floored at 0.0 or min price
Fixed Increase	Price = Base + Fixed Amount	$15.00 markup = $115.00	Clamped if above maximum_price
Fixed Price	Price = Fixed Value	Override = $49.00	Fixed final price regardless of base

---

Condition Triggers

• Always (Unconditional): Rule applies constantly while status is active.
• Date & Time Schedule: Evaluated strictly using your WordPress site's configured local timezone (wp_timezone()), eliminating UTC offset mistakes.
• Stock Quantity: Intercepts real-time inventory levels. When inventory changes, cached prices are invalidated automatically via StockHooks.
• Cart Item Quantity: Evaluates the aggregate line-item quantity in the customer's cart, applying wholesale or bulk discount tiers at checkout.
• Total Sales Count: Evaluates the product's cumulative sales counter (total_sales meta).

---

Price Preview Simulator

The built-in simulator under WPCalibrate > Smart Price Rules > Price Preview enables testing without touching live customer prices:

• Dropdown pre-populates your store's products with instant search.
• Set a simulated purchase quantity.
• Diagnostic box outputs:
  • Base catalog price
  • Winning rule name and priority
  • Calculation formula applied
  • Safeguard clamping indicators (e.g. (Clamped by minimum price protection))
  • Evaluated condition status for all candidate rules

---

In-Dashboard GitHub Auto-Updates

This plugin contains a native update mechanism linked to its official GitHub repository. When a new release tag is published on GitHub, WordPress will automatically display an update notification under Dashboard > Updates and Plugins, allowing standard 1-click in-dashboard updates.

---

Developer Hooks & Filters

Customizing Calculated Prices

add_filter( 'wpcalibrate_spr_calculated_price', function( float $price, WC_Product $product, ?Rule $rule, array $context ): float {
    // Custom post-calculation modification
    return $price;
}, 10, 4 );

Extending Deterministic Resolution

add_filter( 'wpcalibrate_spr_resolved_winning_rule', function( ?Rule $winner, array $candidate_rules, WC_Product $product ): ?Rule {
    // Custom winner selection override
    return $winner;
}, 10, 3 );

Cache Flushing

do_action( 'wpcalibrate_spr_clear_all_caches' );

---

Changelog

[1.0.1] - 2026-10-07

• Overview Tab: Streamlined dashboard header layout, removed oversized banner logo, and added generous tab margin hierarchy.
• Add/Edit Rule Tab: Resolved field collision between Rule Name and Status; restructured form into 4 distinct semantic cards with responsive 12-column grid layout; eliminated WordPress core .regular-text fixed width.
• Price Preview Tab: Pre-populated published store products directly in <select id="preview_product_id"> with title, ID, SKU, and regular catalog price; updated Select2 to minimumInputLength: 0 for immediate dropdown browsing; added vertical alignment spacer and ample button spacing.
• Rules Tab: Fixed unescaped HTML currency in Adjustment column (wp_kses_post), expanded Actions column to 250px, and added horizontal responsive container.
• In-Dashboard Updater: Added GitHubUpdater.php integrating native WordPress plugin update notifications directly from GitHub releases.
• Automated Tests: Expanded test suite covering Overview, Rules, Rule Editor 4-card layout, Preview page, and GitHubUpdater. 100% test pass rate across all 5 test suites.

[1.0.0] - 2026-10-06

• Initial production release.
• Core deterministic pricing engine (PriceEngine.php, PriorityResolver.php, AdjustmentCalculator.php, PriceGuard.php).
• HPOS (custom_order_tables) and Cart/Checkout Blocks (cart_checkout_blocks) declared compatibility.
• 3 custom database tables (wpcalibrate_price_rules, wpcalibrate_price_rule_targets, wpcalibrate_price_history).
• Real-time Price Preview simulator with conflict diagnostics.
• Non-compounding cart pricing hooks and variation price range filters.

---

License & Support

• License: GPL-2.0-or-later. See license.txt for details.
• Author: WPCalibrate
• Support Email: support@wpcalibrate.com
• Marketplace: https://marketplace.wpcalibrate.com/
• WhatsApp Support: +447474795976