Using Marks

This walkthrough goes from a fresh install to badges on the storefront, then covers the manual badge, the shortcode, CSS theming and the developer hooks.

1. Turn on the badges you need

Open the Marks menu, switch Enable badges on, and tick the automatic badges that match how you sell, usually Sale and New to start, adding Low stock and Bestseller as your catalogue grows. Each badge has an optional label field; leave it blank to use the translated default. The live preview reflects your label, shape, case and colour choices as you type.

2. Choose where badges show

Set placement: the single product page, the shop/category/tag listings, or both. Most stores enable both so a promo reads the same on the grid and on the product page. Each context has its own cap.

3. Tune the thresholds

The thresholds decide when automatic badges fire:

• Newness window, shorten it (for example to 14 days) if your catalogue turns over fast, so New stays meaningful. Counted from each product’s created date.
• Low-stock threshold, set the quantity at which urgency helps, for example 5. Only applies to products with WooCommerce stock management enabled.
• Bestseller threshold, set it where a product genuinely qualifies as a top seller; it reads total lifetime units sold.
• Free-shipping classes, list the shipping-class slugs that should earn a Free shipping badge.

To verify Low stock quickly, temporarily raise the threshold on a stock-managed product and confirm the badge appears at the expected quantity.

4. Keep the sale promo clean

If you enabled the Sale badge, turn on Hide theme “Sale!” flash so the theme’s default corner flash does not compete with the Marks badge. Both conditions must be true for the flash to be hidden, the toggle on its own does nothing unless the Sale badge is also enabled.

5. Set the appearance and caps

Pick a shape (pill or square), decide on uppercase, and set the per-context caps. When a product matches more rules than the cap allows, the lowest-priority badges drop, the order is manual, sale, new, low stock, bestseller, discount, free shipping, out of stock, so your most important badges always survive.

6. Add a manual badge

For merchandising the automatic rules cannot express, Staff pick, Editor’s choice, set the store-wide label and colour under the manual badge section, then add the meta _marks_manual_text to the products that should carry it. The meta value is the text that renders, so each product can show its own wording. Optionally add _marks_manual_style (accent, success, warning, danger or neutral) to recolour a single product’s badge. The manual badge has the highest priority, so it is the last to be dropped by a cap.

7. Place badges with the shortcode

To render a product’s badge group outside the default hooks, in a page, post or widget, use [marks_badges]:

[marks_badges]
[marks_badges id="123"]
[marks_badges id="123" context="loop"]

With no attributes it uses the current global product, then the product on a single-product page. id targets a specific product; context is single (default) or loop and only changes the layout class, not which badges qualify. The shortcode enqueues the badge stylesheet on that page only when the product actually has badges to show, and returns nothing when badges are disabled.

Theming with CSS

Badges are server-rendered, absolutely positioned over the product image (z-index: 2), so they add no layout shift. The storefront styling is built entirely on --marks-* custom properties, so you can re-skin from your theme stylesheet without overriding markup:

.marks-badges {
  --marks-ink: #1a73e8;        /* the signature accent colour */
  --marks-radius: 4px;          /* pill radius */
  --marks-font-size: 0.72rem;
  --marks-gap: 0.5rem;
  --marks-bg-success: #1f7a3d;  /* per-semantic-colour overrides */
}

--marks-ink re-inks the accent badge and the primary fill in one line. Other tokens cover gap, inset, radius (pill and square), padding, font size/weight and each semantic background (--marks-bg-accent, --marks-bg-success, --marks-bg-warning, --marks-bg-danger, --marks-bg-neutral). A two-stage “stamp press” entrance animation runs only under prefers-reduced-motion: no-preference, and dark-mode inks are applied automatically under prefers-color-scheme: dark. There is no theme template override, the markup is fixed; CSS is the supported customisation surface.

Developer hooks

Three hooks are exposed for extension. Add these in your theme functions.php or a small plugin.

Adjust or add badges before they are de-duplicated and capped, for example, drop the sale badge on a specific category:

add_filter(
    'storefront_kit_product_badges',
    function ( array $badges, WC_Product $product, string $context, array $settings ): array {
        if ( has_term( 'clearance', 'product_cat', $product->get_id() ) ) {
            $badges = array_filter(
                $badges,
                static fn ( $badge ): bool => $badge->text !== __( 'Sale', 'marks' )
            );
        }
        return array_values( $badges );
    },
    10,
    4
);

Each Badge has a public ->text and ->style. The filter runs in priority order; the cap is applied afterwards.

Alter the sanitised settings before they are written to the option:

add_filter( 'marks_sanitize_settings', function ( array $clean, array $raw ): array {
    $clean['max_badges_loop'] = 2; // force a hard limit, ignoring the form
    return $clean;
}, 10, 2 );

Add your own controls to the admin settings page, after the manual-badge card:

add_action( 'marks_admin_settings_after_manual_table', function ( array $settings ): void {
    echo '<p class="description">Your custom note or field here.</p>';
} );

Do not rely on the engine’s secondary_text meta, Marks keeps that badge disabled by design.

Polski overlap

Polski includes its own product badges. Do not run Marks if that module is enabled, pick one badge system. See Standalone storefront plugins.