My custom badge does not show, or shows in the wrong color

How Volume reads the custom.badge metafield, why an unmatched badge comes out black, and why a variant badge never appears on a product card.

Beyond Sale, Sold out and Preorder, Volume can show badges you invent yourself — Handmade, Last pair, Bestseller, New in. They are driven by a metafield, not by a theme setting, and that is where almost every support case starts.

How it works

Volume reads a metafield with the namespace custom and the key badge. It must be a list type (a list of single line text values), because the theme loops through the values and prints one badge per value.

The badge text on the storefront is the metafield value itself, printed verbatim. The Badge 1 to Badge 4 fields in Theme settings → Product badges → Custom badges do not create badges — they only tell the theme which colours to use for which value.

So the flow is: add the value on the product, then (optionally) name that same value in Badge 1–4 and pick its Text and Background colours.

Why it is not showing at all

• The metafield is a single-line text instead of a list — the theme finds nothing to loop over.
• The namespace or key is wrong. It has to be exactly custom.badge.
• The product is sold out. Custom badges only render while the product is available; a sold-out product shows the Sold out badge instead.
• Show badges is off in the Price block on the product page.

Why it is showing in the wrong colour

If a value does not match any of Badge 1–4, the badge still renders — with the theme's default badge colours, which is the colour scheme's text colour as the background. That solid black pill is the usual "wrong colour" report.

Matching is case-insensitive but otherwise exact. New in matches new in and NEW IN, but not New-in, Newin, or New in with a trailing space. Re-type the value in Badge 1 rather than pasting it, and check for stray spaces on the product.

A variant-level badge never appears on a product card. Product cards read only the product-level custom.badge metafield, so a badge set on a single variant shows on the product page but not in collection grids or carousels.

On the product page, both levels are read and both sets render — if the same value is set on the product and on the variant, the badge appears twice.

Four colour slots is not a limit on how many badge values you can use — it is a limit on how many can be coloured. Values beyond those four still show, just in the default style. Keep Badge 1–4 for your evergreen labels and let seasonal one-offs fall back.

All of the badge settings, including Make transparent and the Sale badge's Percentage / Text styles, are covered in Product Badges.