Direct answer
To show a reliable WooCommerce Sold Out badge, read the current product that WooCommerce is already rendering, ask WooCommerce whether that product is in stock, and add one escaped badge only on a documented product-image surface.
Do not change stock status, hide products, disable Add to cart, replace templates, search the page with arbitrary selectors, or run a sitewide JavaScript observer for a display-only label.
Sold Out Badge for WooCommerce Products follows that boundary. Free adds one store-wide text badge. Pro adds bounded category words and colors, an optional product return date, and separate wording only when WooCommerce already permits backorders.
WooCommerce must remain the stock authority
A badge is a presentation of inventory state, not inventory state itself. The safe decision is based on the current WooCommerce product's stock result.
The official WooCommerce content-product.php template shows how catalog output is assembled around the current product and documented hooks. A focused badge plugin can attach to that rendering flow without owning the product query, image, title, price, or Add to cart behavior.
The plugin should never infer "sold out" from:
- a CSS class copied from one theme;
- an absent Add to cart button;
- a price of zero;
- a hidden catalog item;
- a variation selector's current DOM state;
- an old cached page;
- a product ID guessed from surrounding markup.
Those signals can mean many other things. WooCommerce's current product object is the narrower authority.
Why simple badge plugins often become unreliable
Public support threads show the same visible pain through different rendering owners. A merchant working with a block-based product page needed plugin-code and DOM-selector changes and then saw duplicate badges. Another thread questioned whether a focused plugin was obsolete while badges appeared on the wrong product or not at all. A store owner who had tried two alternatives still asked for a current out-of-stock plugin that worked.
These complaints are not proof of one universal bug. They point to three ownership failures:
- the plugin cannot identify one unambiguous current product;
- both classic and block hooks render the same plugin output;
- the theme or another plugin already owns a badge on that surface.
A safe implementation should render nothing when product context is ambiguous and deduplicate its own classic and block paths for the same product surface.
Support a finite set of rendering surfaces
A bounded first release can support:
- the native classic WooCommerce product loop;
- the native classic single-product image area;
- the WooCommerce Product Image block when its block context identifies one current product;
- the product image gallery block on the single-product surface when the same context is available.
It should not claim every page builder, quick-view panel, variation gallery, product carousel, theme override, or headless storefront. Each one can own a different query and markup contract.
When a builder bypasses the supported hooks, the correct failure is no StoreFixKit badge, not a selector editor that lets the merchant patch arbitrary DOM.
Prevent duplicate output by surface, not only product ID
One product can pass through several render callbacks during a page request. Deduplication should distinguish the intended surface:
loopfor catalog or archive output;singlefor the main product page.
Classic and block callbacks that refer to the same product and same surface should resolve to one logical key. Rendering the first badge marks that key used; later equivalent callbacks return the incoming markup unchanged.
Do not use a global "one badge per product ID" rule across the entire request. The same product may legitimately appear once in the main page and once in a related-products loop.
Backorders are not the same as sold out
WooCommerce can report a product as not currently in stock while still allowing backorders. A Free Sold Out badge would be misleading if the product remains purchasable.
The safe default is:
| WooCommerce state | Free result |
|---|---|
| In stock | No Sold Out badge |
| Out of stock and not purchasable from stock | Show configured badge |
| Backorders allowed | Preserve WooCommerce behavior; no Free Sold Out badge |
| Missing or ambiguous product | Render nothing |
Pro may show separate backorder words only when WooCommerce already says backorders are allowed. The words do not enable backorders or change inventory.
Return dates must stay display-only
An expected return date can help shoppers, but it is not a restock schedule. Store one real YYYY-MM-DD date on an explicitly edited product, validate the calendar date, and append it to the badge only on a supported product surface.
The date must not:
- change stock quantity or status;
- schedule a restock;
- enable Add to cart;
- promise supplier performance;
- create a countdown;
- scan the catalog for expired dates.
If the date is missing or malformed, omit it and keep the last valid global badge settings.
Category rules should not rewrite products
Pro can resolve one category layer from the current product's category IDs. A finite rule can include up to 50 selected categories, one short label, and two validated colors.
The rule is evaluated at render time. It does not need a product scan, bulk metadata rewrite, custom table, cron job, or cache purge. Store-wide Free settings remain the fallback.
The paid market for broader badge builders is established, including WooCommerce Product Badges and Labels and YITH WooCommerce Badge Management. That does not justify rebuilding a campaign engine. It supports a smaller product for merchants who want one automatic stock-driven outcome without marketing rules, scheduling, analytics, or design complexity.
Keep the badge accessible
The badge words should be real text in the document, not CSS pseudo-content. Keep them short enough to fit mobile product images. Validate foreground and background colors, and use a stable class scoped to StoreFixKit output.
The badge should not cover the entire product image or block the product link. The layout owner remains the theme or WooCommerce. StoreFixKit should position only its own small label inside the supported image wrapper.
Color controls cannot guarantee perfect accessibility for every image and theme, so test actual contrast and focus behavior on the live design.
Test truth and layout together
| Product case | Expected result |
|---|---|
| Published in-stock product | No StoreFixKit badge |
| Published out-of-stock product | One badge on each supported intended surface |
| Backorderable product | No Free Sold Out badge; optional Pro backorder words only |
| Product with valid return date | Date appears only with eligible Pro badge output |
| Invalid return date | No date suffix and no product write during rendering |
| Classic and block callback both run | One badge for that product and surface |
| Related product repeats main product | One badge can appear in each distinct legitimate surface |
| Builder bypasses native hook | No forced selector patch |
| Plugin deactivated | Native markup returns immediately |
Test desktop and mobile for horizontal overflow, badge clipping, product-link access, price and Add to cart behavior, and duplicate labels. Then compare stock, backorders, price, visibility, image data, cart, checkout, and orders before and after. A badge plugin should change none of them.
Security and resource boundary
Global and category settings require a WooCommerce-management capability and nonce. A product return date requires permission to edit that exact product and a separate product-bound nonce.
On the storefront, the plugin needs only:
- one bounded option read;
- the already current product's stock check;
- one small conditional stylesheet when badge output is possible;
- no runtime write.
It needs no custom table, cron, catalog scan, remote request, telemetry, customer cookie, frontend JavaScript, image generation, or arbitrary selector storage.
Missing WooCommerce, invalid settings, ambiguous product context, unsupported output, expired Pro, or an unavailable license service should cause no fatal error and preserve native WooCommerce behavior.
The Sold Out Badge documentation includes real screenshots, exact setup, duplicate troubleshooting, rollback, uninstall ownership, and support evidence.
Beginner launch checklist
Create three test products
Use one in-stock, one fully out-of-stock, and one backorderable product. Record their stock settings and native storefront output.
Configure readable words and colors
Start with a short label. Check contrast against light and dark product images on desktop and mobile.
Test every real product surface
Open the shop, category archive, single-product page, related products, quick view, and builder templates actually used. Record which surfaces are native and which have another owner.
Test the off path
Disable the badge, deactivate Pro, deactivate Free, and restore each. Native stock truth and purchasing behavior should remain unchanged.
Test rollback
Move to the known baseline package and back, comparing badge count, output placement, stock, backorders, price, image, cart, checkout, and a disposable order.
FAQ
Does the badge change stock status?
No. It reads WooCommerce's current result and changes only StoreFixKit-owned display markup.
Why is there no badge on a backorderable product?
Because the product can still be purchased. Free avoids calling it sold out. Pro can show separate backorder words only when WooCommerce already allows backorders.
Why does a page builder show no badge?
The builder may own a different product-image component and bypass the supported WooCommerce hooks. The plugin stays silent instead of patching arbitrary selectors.
Can the expected return date restock a product automatically?
No. It is display-only text and never changes stock or schedules a task.
What happens when Pro expires?
The Free store-wide badge continues locally. Category words, return-date display, and backorder wording require an active product-bound license.
Focused plugin
Use the one-job implementation.
Show one clear Sold Out badge on supported WooCommerce product images only when WooCommerce reports that the current product is not in stock.