📄 Plugin Documentation

Product Badge Rules — Smart Badges
for WooCommerce

Show the right badge on the right product, automatically. Sale %, new arrivals, low stock, price ranges, tags and backorders — driven by live WooCommerce data, with full per-product control. No code, no image uploads, no front-end JavaScript.

● GPL v2 or later ● WordPress 6.3+ ● PHP 8.0+ ● WooCommerce 8.0+ ● HPOS Compatible ● Free
01 — Introduction

What is Product Badge Rules?

Product Badge Rules (by Storzen) adds automatic product badges and labels to your WooCommerce store. Instead of editing every product by hand, you create a badge once, pick a rule, and the plugin shows it on every product that matches — and stops showing it the moment the product no longer matches.

Badges are plain HTML and CSS rendered on your server. There is no front-end JavaScript, one stylesheet loads only on WooCommerce pages that actually show a badge, and all active badges are fetched in a single cached query.

⚙️
9 Automatic Rules
On sale, new arrival, featured, low stock, out of stock, hot seller, price range, product tag and on backorder. Badges update themselves when prices, stock or sales change.
Free
🎯
Per-Product Override
Hide the badge on one product, or give it custom text such as “Limited Edition” — from the product edit screen or Quick Edit.
Free
🗂️
Category Targeting
Limit any badge to one or more product categories — for example a “Summer Sale” badge that only appears in your Summer collection.
Free
🎨
Badge Designer
Colour pickers, four shapes, eight positions and a live preview. Match any brand palette without touching CSS.
Free
📅
Scheduling & Priority
Optional start and end dates for Black Friday, Christmas or any timed promotion. Priority numbers decide which badge wins when several match.
Free
🔢
Live Matched Count
The badge list shows how many published products each badge is currently on. Click the number to refresh it without reloading the page.
Free
🔁
Sale Flash Replacement
Hide WooCommerce’s default “Sale!” bubble on products that show one of your badges — works with classic themes and block themes.
Free
⚡
Performance First
One cached query for all badges, pure-CSS output, conditional asset loading, HPOS compatible. Built to stay out of your way.
Free
yourstore.com → Shop
👟Save 30%
Trail Runner Pro
$100.00 $70.00
🧢Only 3 left!
Summit Cap
$24.00
🎒New
Day Pack 22L
$89.00
🧣Sold Out
Merino Scarf
$45.00
🔦Pre-order
Headlamp X2
$59.00
🥤Under $20
Steel Bottle
$15.00
02 — Requirements

System Requirements

WooCommerce is a hard dependency. The plugin declares it in its header (Requires Plugins: woocommerce) and shows an admin notice if WooCommerce is missing. No external services or libraries are needed.

ComponentMinimumNotes
WordPress6.3Tested up to 7.1
PHP8.0Typed code, namespaced classes
WooCommerce8.0Required. Tested up to 11.2
DatabaseMySQL / MariaDBOne custom table, {prefix}badgify_badges, created on activation
🛒
WooCommerce
8.0+ (tested to 11.2)
🗄️
HPOS
Declared compatible
📦
Variable Products
Supported
🧱
Block Themes
Product Collection & sale badge block
🏬
Classic Themes
Standard WooCommerce hooks
🌐
Translation-ready
Text domain included
03 — Installation

Installation

From WordPress.org (Recommended)

1

Search in Plugins

In your WordPress admin go to Plugins → Add New and search for “Storzen Product Badge Rules”.

2

Install & Activate

Click Install Now, then Activate. The plugin creates its database table and adds three starter badges (Sale, New, Hot) on first activation.

3

Open the menu

Click Product Badge Rules in the admin sidebar and open All Badges.

Manual Upload

1

Download the ZIP

Download storzen-product-badge-rules-for-woocommerce.zip.

2

Upload via Admin

Go to Plugins → Add New → Upload Plugin, choose the ZIP and click Install Now.

3

Activate

Click Activate Plugin. Make sure WooCommerce is installed and active first.

💡
Works straight away

The three starter badges are live as soon as you activate: a red Sale badge, a green New badge (products from the last 30 days) and an orange Hot badge (50+ sales). Edit or delete them any time.

04 — Quick Start

Quick Start

Create your first badge in about a minute. This example adds a “Save 30%” style badge to every product on sale.

1

Add a badge

Go to Product Badge Rules → All Badges and click Add New Badge.

2

Name it and choose a rule

Enter an internal Badge Name (customers never see it) and choose On Sale as the Trigger Rule.

3

Write the label

Set Label Text to Save {pct}. The {pct} token is replaced with the real discount, so a product at 30% off shows “Save 30%”.

4

Style it

Pick background and text colours, a shape and a position. The live preview updates as you type.

5

Save

Click Save Badge. Open your shop page — the badge is already live.

ℹ️
Remove the duplicate “Sale!” bubble

With Display → Replace WooCommerce Sale Flash on (the default), WooCommerce’s own bubble is hidden on every product that shows one of your badges, so products never carry two sale badges.

05 — Concepts

How a Badge Is Chosen

For each product the plugin walks through your active badges in priority order and shows the first one that matches. The free version shows one badge per product.

1

Per-product override

If the product is set to Hide badge, nothing is shown and no rules are evaluated.

2

Active & scheduled

Only badges with Status on and inside their optional Active From / Until window are considered.

3

Rule + category match

Badges are checked in Priority order (lowest number first). A badge matches when its rule matches and the product is in one of the badge’s target categories (or no categories are set).

4

Custom text (optional)

If the product is set to Custom text, your text replaces the label of the matched badge — or, when no rule matches, a neutral dark badge is shown.

💡
Order your badges on purpose

Give the most important badge the lowest priority number. For example Sold Out at 5, Low Stock at 8, Sale at 10 — a sold-out product on sale then shows “Sold Out”, not “Sale”.

06 — Feature

The 9 Badge Rules

The Trigger Rule decides which products get a badge. Rules read live WooCommerce data, so badges appear and disappear on their own.

RuleMatches when…Rule value
On SaleWooCommerce reports the product as on sale (is_on_sale())none
New ArrivalThe product was published within the last N daysdays (empty = global setting, 30)
FeaturedThe product is marked Featured in WooCommercenone
Low StockStock is managed, the product is in stock and quantity is between 1 and the thresholdthreshold (empty = global setting, 5)
Out of StockThe product is not in stocknone
Hot SellerTotal sales reach the minimummin sales (empty = global setting, 50)
On BackorderStock status is “On backorder”none
Price RangeThe current price is inside a min–max rangemin and/or max price
Product TagThe product has at least one of the selected product tagsone or more tags

On Sale

sale

Use {pct} in the label to show the discount, for example Save {pct} → “Save 30%”. For variable products the percentage compares the highest regular price with the lowest sale price.

New Arrival

new

Based on the product’s published date. Leave the rule value empty to use the global Rule → New Arrival — Days setting.

Low Stock

low_stock

Needs Manage stock enabled on the product. Use {qty} in the label: Only {qty} left! → “Only 3 left!”. Out-of-stock products are not “low stock” — use the Out of Stock rule for those.

On Backorder

backorder

For “Pre-order” or “Ships in 2 weeks” labels. A product set to On backorder is still purchasable, so it does not match the Out of Stock rule.

Price Range

price_range

Enter a Min, a Max, or both. Leave Max empty for “and above” (a Premium badge from 100), or Min empty for “up to” (an Under $20 badge with Max 20).

The current price is used, so a product on sale is judged by its sale price. Variable products use their lowest variation price. Products without a price never match.

Product Tag

product_tag

Tick one or more tags — for example Eco-friendly or Gift idea. The picker lists your 200 most-used tags plus any tag already selected on the badge.

⚠️
Price Range and Product Tag need a value

Saving a Price Range badge with no min/max, a range whose maximum is below its minimum, or a Product Tag badge with no tag is rejected with a clear message so you never end up with a badge that can never match.

07 — Feature

Label Tokens

Tokens are placeholders in the Label Text that the plugin replaces with real values for each product.

TokenWorks withResult
{pct}On Sale ruleDiscount percentage, rounded — Save {pct} → “Save 30%”
{qty}Low Stock ruleUnits left — Only {qty} left! → “Only 3 left!”

Tokens only work with the rule listed. Used with any other rule they are left in the text as typed.

08 — Feature

Badge Designer

Every badge has its own colours, shape and position, with a live preview in the editor.

Colours

Choose a Background and Text Color with the WordPress colour picker.

Shapes

Sale
Rounded
Sale
Square
-30%
Circle
Sale
Ribbon

Positions

Eight positions on the product image — the four corners and the four edge midpoints. The centre is intentionally left free.

top-left
top-center
top-right
mid-left
—
mid-right
btm-left
btm-center
btm-right

Slugs used in the database and CSS:

top-left top-center top-right middle-left middle-right bottom-left bottom-center bottom-right
💡
Badge hidden behind the image?

Raise Display → Badge Z-Index (default 99). Values like 999 fix most theme overlays.

09 — Feature

Scheduling & Priority

Scheduling

Set Active From and/or Active Until to run a badge for a limited time — Black Friday, a launch week, a holiday sale. Outside the window the badge is hidden automatically. Leave both empty to always show it.

Priority

When more than one badge matches a product, the one with the lowest priority number wins. The starter badges use 10 (Sale), 20 (New) and 30 (Hot).

Status

Switch a badge on or off with the Status toggle — in the editor or straight from the badge list — without deleting it.

10 — Feature

Category Targeting

In the badge editor, the Category Targeting section lists your product categories. Tick one or more and the badge only appears on products assigned to those categories. Leave all unticked to show the badge on every product.

ℹ️
Exact category match

Targeting matches the categories a product is directly assigned to. Ticking a parent category does not automatically include products that sit only in its sub-categories — tick the sub-categories as well.

Category targeting combines with the rule: a Summer Sale badge using the On Sale rule and the “Summer” category shows only on sale products in Summer. A sale product in another category falls through to your next matching badge, such as a general Sale badge.

11 — Feature · New in 1.0.2

Per-Product Override

Sometimes one product needs its own treatment. Every product has a Product Badge box on its edit screen, and the same options appear in the product list Quick Edit panel.

Product Badge
Auto — use badge rules
Hide badge on this product
Custom text
Limited Edition
Custom text keeps the colours of the matching badge rule, or uses a neutral dark badge when no rule matches.
Auto
The badge rules decide. This is the default and stores nothing.
Hide badge
No badge on this product, whichever rules match. With Replace WooCommerce Sale Flash on, WooCommerce’s own “Sale!” bubble is hidden too, so the product shows no badge at all.
Custom text
Your own label, up to 30 characters.

How custom text looks

  • If a badge rule matches the product, your text replaces that badge’s label and keeps its colours, shape and position.
  • If no rule matches, a neutral dark badge (dark grey, white text, rounded, top-left) is shown. Developers can change this with the badgify_custom_badge_style filter.
  • An empty custom text behaves like Auto.

Where to set it

  • Product edit screen — the Product Badge box in the right-hand column. Saved when you click Update.
  • Quick Edit — in Products → All Products, hover a product and click Quick Edit. The fields are pre-filled with the current setting.
✅
Secure by design

Saving requires the permission to edit that product and a valid nonce. Data is stored as two product meta values (_badgify_override, _badgify_custom_text), read through the WooCommerce product object, so they add no extra query in normal product loops.

12 — Feature

Matched Count

The Matched column in All Badges shows how many published products each badge is currently on, for example “12 products”. It answers “is this rule doing anything?” without browsing your catalogue.

Product Badge Rules → All Badges
Dashboard
All Badges
Display
Rule
Advanced
All Badges
+ Add New Badge
Badge
Rule
Matched
On
Save 30%Summer Sale Only
On Sale
2 products
Pre-orderPreorder
On Backorder
1 product
Under $20Budget
Price Range
1 product
NewNew Arrival Badge
New Arrival
4 products
  • Click a count to refresh it instantly. Otherwise it is cached for 6 hours and cleared whenever you save a badge or change a product’s override.
  • Counts respect category targeting and each variable product is counted once, not once per variation.
  • Products set to Hide badge are not counted.
13 — Store Display

Display Options

Open Product Badge Rules → Display to control where badges appear.

Product Badge Rules → Display
Dashboard
All Badges
Display
Rule
Advanced
Display
Show on Shop / Archive
Shop, category and tag archive pages
Show on Single Product
Individual product pages
Replace WooCommerce Sale Flash
Hide the default “Sale!” bubble where a badge shows
Show Badge Column in Product List
“Badges” column in Products → All Products
Badge Z-Index
Increase if badges sit behind images
99
Save Settings
OptionWhat it does
Show on Shop / ArchiveBadges on shop, category and tag pages and product loops.
Show on Single ProductBadge on the main product image of a single product page. Related-product loops follow the Shop / Archive setting.
Replace WooCommerce Sale FlashHides WooCommerce’s “Sale!” bubble per product, only where one of your badges (or a Hide override) takes its place. Sale products your badges don’t cover keep the theme’s own flash.
Show Badge Column in Product ListAdds a Badges column to Products → All Products showing the badge each product currently gets.
Badge Z-IndexStacking order of badges above the product image (1–9999).
14 — Store Display

Themes & Page Builders

Classic themes

Badges are added through the standard WooCommerce hooks woocommerce_before_shop_loop_item_title (product loops) and woocommerce_before_single_product_summary (single product). Tested with Storefront.

Block themes

Badges also render inside the WooCommerce Product Collection block and on single product pages, and the block theme’s own Sale badge block is hidden per product when one of your badges replaces it. Tested with Twenty Twenty-Five.

Page builders

Builder widgets that render the product loop through the standard WooCommerce hooks show badges. Widgets that replace the loop with fully custom markup may not — if badges are missing in a builder widget, switch to the builder’s WooCommerce-hook-based product loop or contact the builder’s support about hook compatibility.

ℹ️
Stylesheet loading

The badge stylesheet loads on shop, category, tag and single product pages — and on any other page where a badge is actually output (for example a landing page with a Product Collection block).

15 — Admin UI

Admin Screens

The plugin adds a top-level Product Badge Rules menu with five screens. Everything requires the manage_woocommerce capability (Shop Manager and Administrator), and every save is protected by a nonce.

ScreenPurpose
DashboardTotals for all and active badges, display locations, a shortcut to add a badge and the list of active badges.
All BadgesBadge list with rule, Matched count and an on/off toggle. Add, edit and delete badges here.
DisplayWhere badges appear, sale flash replacement, product list column and z-index.
RuleGlobal defaults for rules with an empty rule value: New Arrival days, Low Stock threshold, Hot Seller minimum sales.
AdvancedBadge font size.

The badge editor

Click Add New Badge (or Edit on an existing one). The editor has Basic, Design, Position, Schedule & Priority, and Category Targeting sections, with a live preview on the right.

Product Badge Rules → Add New Badge — Price Range rule
Dashboard
All Badges
Display
Rule
Advanced
Add New Badge
Budget picks
Price Range ▾
Min – 20
Under $20
Save Badge

Products list

With Show Badge Column in Product List on, Products → All Products gains a Badges column. Quick Edit gains the Product Badge override fields.

16 — Reference

All Settings

Global settings live in one WordPress option, badgify_settings, seeded with these defaults on first activation. Each badge itself is a row in the {prefix}badgify_badges table.

KeyDefaultDescription
show_on_archive1Show badges on shop / archive pages and loops
show_on_single1Show badges on single product pages
replace_sale_flash1Hide the WooCommerce “Sale!” flash where a badge is shown
show_product_column1Add the Badges column to the product list
new_days30Default window for the New Arrival rule (1–365 days)
low_stock_threshold5Default threshold for the Low Stock rule
hot_min_sales50Default minimum sales for the Hot Seller rule
badge_z_index99CSS z-index of badges (1–9999)
badge_font_size11Badge text size in px (9–24)
max_badges1Internal. The free version always shows one badge per product

Badge fields

FieldValues
rule_typesale new featured low_stock out_of_stock hot backorder price_range product_tag
rule_valueNumber for new, low_stock, hot; min-max (e.g. 0-20, 100-) for price_range; comma-separated tag IDs for product_tag; empty otherwise
shaperounded square circle ribbon
positiontop-left top-center top-right middle-left middle-right bottom-left bottom-center bottom-right
category_idsComma-separated product category IDs (empty = every product)

Product meta

Meta keyValue
_badgify_overridehide or custom (absent = Auto)
_badgify_custom_textCustom badge text, up to 30 characters (used with custom)
17 — Developers

Developer Hooks

Product Badge Rules is namespaced PHP (Badgify\…) with no global function pollution, and a few small extension points.

Filter: badgify_render_badge

Return false to stop a specific badge from rendering. Receives the default (true) and the badge object.

PHP — hide the “Hot” badge for logged-out visitors
add_filter( 'badgify_render_badge', function ( $render, $badge ) {
	if ( 'hot' === $badge->rule_type && ! is_user_logged_in() ) {
		return false;
	}
	return $render;
}, 10, 2 );

Filter: badgify_custom_badge_style

Changes the look of a Custom text badge on products where no badge rule matches. Return an array with bg_color, text_color, shape and position.

PHP — make manual badges brand-coloured
add_filter( 'badgify_custom_badge_style', function ( $style ) {
	$style['bg_color'] = '#5b4fff';
	$style['shape']    = 'square';
	return $style;
} );

Filter: badgify_rule_map

Maps a rule_type slug to a rule class. A rule class extends \Badgify\Rules\Rule_Abstract and implements matches( \WC_Product $product, string $rule_value ): bool; it can also override label_tokens() to add label placeholders.

PHP — register a custom rule
class My_Clearance_Rule extends \Badgify\Rules\Rule_Abstract {
	public function matches( \WC_Product $product, string $rule_value ): bool {
		return has_term( 'clearance', 'product_cat', $product->get_id() );
	}
}

add_filter( 'badgify_rule_map', function ( $map ) {
	$map['clearance'] = My_Clearance_Rule::class;
	return $map;
} );
⚠️
Custom rules are code-level

Badges whose rule_type is registered through this filter are evaluated by the engine, but the badge editor lists the nine built-in rules only. Custom-rule badges have to be created in code.

Action: badgify_loaded

Fires once the plugin has finished booting (WooCommerce is active and all modules are registered). Use it to run code that depends on the plugin.

Template override

Copy templates/badge.php from the plugin folder to your-theme/badgify/badge.php. The template receives a $badge object with resolved_label, bg_color, text_color, shape and position.

CSS hooks

Selector / variableMeaning
.badgify-badgeEvery badge element
.badgify-pos-{position}Position class, e.g. badgify-pos-top-left
.badgify-shape-{shape}Shape class, e.g. badgify-shape-ribbon
--badgify-z-indexCSS variable set from Display → Badge Z-Index
--badgify-font-sizeCSS variable set from Advanced → Badge Font Size
18 — Performance

Performance & Caching

  • One query for all badges. Active badges load in a single database query, kept in memory for the request and in a 12-hour transient across requests. Saving, deleting or toggling a badge clears it.
  • No per-product queries. Rules are evaluated in PHP on data WooCommerce has already loaded, and per-product overrides are read from the product’s cached meta.
  • No front-end JavaScript. Badges are server-rendered HTML styled by one small stylesheet.
  • Conditional assets. The stylesheet loads only on WooCommerce shop, archive and product pages — or wherever a badge is actually output. Admin scripts and styles load only on the plugin’s own screens, plus a tiny script on the product edit and product list screens for the override box.
  • Admin-only counts. The Matched count runs in the admin only and is cached for 6 hours.
19 — Privacy

Privacy & Data

  • The plugin does not collect, store or transmit any personal data from your visitors.
  • All badge logic runs on your own server using existing WooCommerce product data.
  • No cookies, no external HTTP requests, no third-party services.
  • Stored data: the {prefix}badgify_badges table, the options badgify_settings, badgify_db_version and badgify_version, a few badgify_ transients, and the two optional product meta keys.
  • Deleting the plugin via Plugins → Delete drops the table and removes all options, transients and per-product override meta. Your products, prices and orders are never touched.
ℹ️
Deactivating vs deleting

Deactivating only stops badges from showing — your badges and settings are kept. Data is removed only when you delete the plugin.

20 — Help

Troubleshooting

A badge is not showing on a product

  • Is the badge’s Status on, and is today inside its Active From / Until dates?
  • Is Show on Shop / Archive (or Single Product) enabled under Display?
  • Does the product match the rule? Check the rule definition in The 9 Badge Rules — for example Low Stock needs Manage stock on the product.
  • If the badge has Category Targeting, is the product assigned to one of those categories directly?
  • Is the product’s Product Badge box set to Hide badge?
  • Is another badge with a lower priority number matching the same product? Only one badge is shown.

The badge is behind the product image

Increase Display → Badge Z-Index (try 999).

Two sale badges appear

Turn on Display → Replace WooCommerce Sale Flash. If a second bubble remains, your theme or builder draws its own sale label outside WooCommerce’s standard sale-flash hooks and needs its own setting.

The Matched count looks out of date

Click the count to recompute it immediately. Counts refresh on their own every 6 hours and whenever a badge or override is saved.

A Price Range badge doesn’t show on a product

The rule uses the product’s current price (sale price while on sale; lowest variation price for variable products). Products with no price never match.

21 — FAQ

Frequently Asked Questions

Can I show more than one badge on a product?
The free version shows the single highest-priority matching badge per product (lowest priority number wins). Multi-badge stacking is planned as a Pro feature.
How do I hide the badge on one specific product?
Edit the product, find the Product Badge box in the right-hand column (or use Quick Edit in the product list), choose Hide badge on this product and update. Switch back to Auto any time.
Can I give one product its own badge text?
Yes. Choose Custom text in the Product Badge box and type up to 30 characters, for example “Limited Edition”. If a rule also matches the product, your text uses that badge’s colours and position; otherwise a neutral dark badge is shown.
How do I create a “Pre-order” badge?
Create a badge with the On Backorder rule and the label “Pre-order” (or “Ships in 2 weeks”). It shows on every product whose stock status is On backorder.
How do I create an “Under $20” or “Premium” badge?
Use the Price Range rule. Enter Max 20 for “Under $20”, or Min 100 (Max empty) for “Premium”. The current price is used, so a product on sale is judged by its sale price.
Can I show a badge only on products with a certain tag or category?
Yes, both. Use the Product Tag rule to badge products by tag, or Category Targeting to limit any badge to chosen categories. They combine: for example a Sale badge limited to your Summer category.
Can I schedule a badge for a sale or holiday?
Yes. Set Active From and Active Until on the badge. Outside that window it is hidden automatically.
Will this slow down my store?
No. Badges are fetched in one cached query, evaluated in PHP memory and rendered as plain HTML/CSS. There is no front-end JavaScript and no per-product database query.
Does it work with variable products?
Yes. Sale detection, stock and the other rules work with simple and variable products. The Price Range rule uses the lowest variation price, and the {pct} token compares the highest regular price with the lowest sale price.
Does it work with block themes and the Product Collection block?
Yes — badges show in the Product Collection block, on shop and category pages and on single product pages, and the block theme’s Sale badge is hidden per product where your badge replaces it. Tested with Twenty Twenty-Five (block) and Storefront (classic).
Does it work with Elementor or Divi?
Builder widgets that render the product loop through the standard WooCommerce hooks will show badges. Widgets that replace the loop with fully custom markup may not.
Can I change the badge HTML?
Yes. Copy templates/badge.php to your-theme/badgify/badge.php and edit it. See Developer Hooks.
Is it compatible with WooCommerce HPOS?
Yes. The plugin declares compatibility with High-Performance Order Storage.
What happens to my data if I delete the plugin?
Deleting the plugin from Plugins drops the badge table and removes all plugin options, transients and per-product override meta. Products, prices and orders are not touched.
22 — Changelog

Changelog

1.0.2Latest
Per-product badge override — Auto, Hide badge or Custom text on the product edit screen and in Quick Edit.
Price Range rule — badge products by current price (e.g. “Under $20”, “Premium”).
Product Tag rule — badge every product that has the selected tags.
On Backorder rule — for “Pre-order” and “Ships in 2 weeks” badges.
Matched count ignores products whose badge is hidden.
Server validation messages are now shown in the editor instead of a generic error.
Uninstall also removes per-product override data.
1.0.1
Category targeting — restrict any badge to selected product categories.
“Matched” column in All Badges, with click-to-refresh.
Fix: boot callback corrected so all badge functionality loads on every request.
Fix: admin scripts and styles load only on the plugin’s own screens.
Fix: saving one settings screen no longer resets options on another.
Fix: Badges column appears in the WooCommerce product list; badges sit on the image in block themes.
1.0.0Initial release
Six badge rules: on sale ({pct}), new arrival, featured, low stock ({qty}), out of stock, hot seller.
Badge designer with colour pickers, four shapes, eight positions, scheduling and priority, with live preview.
Option to replace the default WooCommerce sale flash; Badges column in the product list.
Two-layer caching and WooCommerce HPOS compatibility.