Minimum Purchase WooCommerce

Set a minimum purchase requirement for your WooCommerce store — either by total cart weight or by product quantity — and stop customers from checking out until it's met. Includes a live progress bar element and dynamic data tags for Bricks Builder, plus AJAX-powered cart updates.

Contributors: Yusuf Bahrami, Peyvast Agency Tags: woocommerce, minimum purchase, minimum order, cart weight, quantity, bricks builder Requires at least: WordPress 5.0, WooCommerce 5.0 Tested up to: WordPress 6.7 Requires PHP: 7.4 Stable tag: 1.0.3 License: GPLv3 or later License URI: https://www.gnu.org/licenses/gpl-3.0.html

✨ Features

• Weight-based minimum — require a minimum total cart weight, based on your WooCommerce weight unit (kg, g, lb, oz).
• Quantity-based minimum — require a minimum number of items in the cart.
• Blocks checkout — the order button is disabled and the customer is redirected back to the cart until the requirement is met.
• Live AJAX status — the frontend status widget refreshes automatically as the cart changes, without page reloads.
• Bricks Builder integration — a native Minimum Purchase Progress Bar element with fully styleable controls, plus dynamic data tags you can use anywhere in Bricks.
• Order weight meta — item and order weights are stored on orders at purchase time (HPOS-compatible), so historical weights survive product changes.
• Configurable error message — choose exactly what customers see when the requirement is not met.
• Decimal places control — display current values with 0–6 decimals.
• Translation-ready — ships with fa_IR (Persian) translations and a .pot file for other locales.

📦 Requirements

ℹ️ The plugin works without Bricks Builder — the progress bar element and dynamic tags are simply unavailable.

🚀 Installation

1. Download the plugin ZIP (or clone this repository into wp-content/plugins/).
2. In WordPress, go to Plugins → Add New → Upload Plugin and upload the ZIP.
3. Activate Minimum Purchase WooCommerce.
4. Go to WooCommerce → Settings → Minimum Purchase to configure it.

⚙️ Configuration

Under WooCommerce → Settings → Minimum Purchase:

🧱 Bricks Builder

When Bricks is active, the plugin adds:

• Element: Minimum Purchase Progress Bar — a live progress bar showing current vs. required weight/quantity, styleable with native Bricks controls.

• Dynamic tags (group Minimum Purchase):

  Tag	Returns
  {mpw_minimum_purchase_value}	Required minimum (plain number)
  {mpw_current_cart_total_value}	Current cart value (plain number)
  {mpw_remaining_amount_value}	Remaining amount (plain number)
  {mpw_unit}	Current unit (e.g. kg)
  {mpw_progress_percent}	Progress percentage with %
  {mpw_order_item_weight}	Unit weight of the current order item
  {mpw_order_item_total_weight}	Total weight of the current order item (unit × qty)
  {mpw_order_total_weight}	Total weight of the current order
  {mpw_order_unit}	Weight unit stored on the order

• Legacy tags (group Cart Condition): {cart_minimum_order_current}, {cart_minimum_order_minimum}, {cart_minimum_order_percentage}, {cart_minimum_order_unit}, {cart_minimum_order_met}, {cart_minimum_order_checkout_allowed} — kept for backward compatibility.

🧑‍💻 Developer API

All helpers are prefixed and can be used from your own code:

// Is the plugin enabled?
mpw_is_enabled();

// Current mode: 'weight' or 'quantity'
mpw_get_type();

// Does the cart meet the requirement?
mpw_cart_meets_requirement();

// Full cart status: current, min_value, unit, percentage, remaining, valid, checkout_allowed…
$status = mpw_get_cart_status();

// Human-readable one-liner, e.g. "Current weight: 1.50 kg / Required: 5 kg (30%)"
echo mpw_get_status_message();

Internally the plugin is split into small services under includes/:

Filters & actions

The validation pipeline is the single source of truth (MPW\Validation\Minimum_Purchase::get_cart_status()), used by the checkout check, the AJAX endpoint, the Bricks element, and all dynamic tags — so every surface stays in sync.

🌍 Translations

• Persian (fa_IR) is bundled.
• The .pot file is at languages/minimum-purchase-woocommerce.pot — use it as the base for new translations (e.g. with Poedit).
• Text domain: minimum-purchase-woocommerce.

📄 License

This plugin is licensed under the GNU General Public License v3.0 or later. See LICENSE.

Copyright © 2026 Yusuf Bahrami, Peyvast Agency