Configuration

Everything lives on one screen: a top-level Marks menu in wp-admin (dashicons-tag, capability manage_woocommerce, so shop managers can save it, not just administrators). All settings are stored in a single marks_settings option (an array). Input is sanitised, validated against an allow-list and clamped on save, so an out-of-range number or an unknown colour key can never reach a listing. A sticky Live preview panel on the right updates as you type; with JavaScript off it shows a representative static set instead of going blank.

Display

Enable badges

The master switch (enabled), on by default. When off, no badges render anywhere and the front-end stylesheet (assets/css/badges.css) is not enqueued at all, zero front-end weight, not just hidden markup.

Placement

Two independent toggles for where badge groups may appear:

• Single product page (show_on_single), badges over the main image on the product’s own page, hooked to woocommerce_before_single_product_summary.
• Shop and category listings (show_on_loop), badges on product thumbnails across the shop, category and tag archives, hooked to woocommerce_before_shop_loop_item_title.

Enable either or both. Each context has its own badge cap (see Appearance).

Automatic badges

Each rule is an independent toggle with an optional custom label. Leave a label blank to use the built-in translated default. The rule logic and the storefront colour it renders in:

Setting key	Shows when	Default	Colour
show_sale_badge	WC_Product::is_on_sale() is true	on	amber (warning)
show_new_badge	the product’s created date is within the newness window	on	green (success)
show_low_stock_badge	stock is managed and remaining quantity is > 0 and ≤ the threshold	on	amber (warning)
show_bestseller_badge	total lifetime units sold ≥ the threshold	on	accent (vermilion)
show_discount_percent_badge	on sale and a positive saving, renders the computed figure, e.g. -20%	off	red (danger)
show_free_shipping_badge	the product’s shipping-class slug is in your list	off	green (success)
show_out_of_stock_badge	WC_Product::is_in_stock() is false	on	grey (neutral)

Custom label fields are sale_badge_text, new_badge_text, low_stock_badge_text, bestseller_badge_text, free_shipping_badge_text and out_of_stock_badge_text. The discount-percent badge has no label field, its text is computed from the regular and sale price.

Hide theme “Sale!” flash

hide_woocommerce_sale_flash (off by default). When on and the Sale badge is enabled, Marks returns false to the woocommerce_sale_flash filter so the theme’s default corner “Sale!” is suppressed and only the Marks badge shows. With either condition unmet, the native flash is left untouched.

Thresholds

Tune when the automatic rules fire. Each value is clamped to a minimum of 1 on save:

• Newness window (days), newness_days, default 30. A product counts as New for this many days after its created date (WC_Product::get_date_created()).
• Low-stock threshold, low_stock_threshold, default 3. Requires WooCommerce stock management on the product; the badge appears when quantity is at or below this number (and still above zero).
• Bestseller threshold, bestseller_threshold, default 25. Total lifetime units sold (get_total_sales()) needed to earn the badge.
• Free-shipping classes, free_shipping_classes, default free-shipping. A comma-separated list of WooCommerce shipping-class slugs. Matching is exact against the product’s own shipping class, find slugs under WooCommerce → Settings → Shipping → Classes.

Appearance

• Badge shape, shape, either pill (default, fully rounded) or square (3px radius). Any other value falls back to pill.
• Uppercase labels, uppercase (off). Uppercases every label and adds light letter-spacing.
• Max badges (product page), max_badges_single, default 4.
• Max badges (listings), max_badges_loop, default 3.

The caps run after de-duplication, and badges are kept in priority order, manual, then sale, new, low stock, bestseller, discount, free shipping, out of stock, so when a product would exceed the cap, the lowest-priority badges drop first. 2-3 keeps listing thumbnails clean.

Manual badge

One store-wide badge, defined here as a label (manual_badge_text) and a colour (manual_badge_style). The colour is one of five semantic keys, accent, success, warning, danger, neutral; anything else is coerced to accent. The signature accent is an inked vermilion (the colour of a rubber stamp), not a UI blue.

Leaving the label blank disables the manual badge. To show it on a product, set the product meta _marks_manual_text to the badge text; the meta value is what renders, so different products can carry different manual labels. Optionally set _marks_manual_style to override the colour for that one product. This is handy for “Editor’s pick” or “Staff favourite” flags without touching code.

What is fixed by design

• Badge colours per automatic rule are not configurable in the admin, they are semantic (sale = amber, bestseller = accent, etc.). Re-skin them with CSS instead (see Using Marks).
• The storefront-kit engine supports a second “secondary” manual badge; Marks deliberately disables it (show_secondary_badge is forced to false) so an unrelated secondary_text meta, from an import or another plugin, can never surface an unexpected badge.

Storage and cleanup

Settings live in the single marks_settings option; a marks_db_version option tracks the schema. Deleting the plugin runs uninstall.php, which removes both options. The per-product manual-badge meta (_marks_manual_text, _marks_manual_style) is intentionally left in place, it is your content, may be shared with other tools, and is cheap to keep. Marks contacts no external service.