Shopify Product Badge — Tags and Metafields Liquid

Tag-based triggers are the simplest badge signal because Shopify product tags are flat, admin-editable, and already loaded in the product drop. The product.tags Liquid variable is an array of strings — contains checks for exact string membership, not substring matching. A tag named "new-arrival" does NOT match contains 'new' — this is a common mistake. The tag "new" must be added verbatim. Advantages: no metafield setup, works on every Shopify plan, visible in the product list view. Disadvantages: tag names are global — adding "sale" to trigger a badge means that tag appears in your admin tag filter and any third-party app that reads tags will see it. Tags are public metadata, not badge configuration. For stores with clean tag taxonomies (tags only for organization), this is the fastest approach.

Metafield-based triggers decouple the badge signal from product organization. The product.metafields.custom.badge_text field stores editor-facing badge content — “New Arrival,” “Best Seller,” “Made in Italy.” The tag "custom-badge" acts as a gate: only products with this tag AND a filled-in metafield get a custom badge. This two-factor system prevents every product with an accidentally-filled metafield from showing a badge. Editors add the tag, fill the text, and the badge appears. The metafield stores only the display text — the badge color/style is determined by the CSS class, not the metafield value. This separation means editors can’t break the design by typing “hot pink” into the metafield.

The priority system resolves conflicts when a product matches multiple badge conditions simultaneously. A product tagged both "sale" and "new" should show the sale badge — the more urgent signal. A sold-out product with a "new" tag should show “Sold Out” because the customer literally cannot purchase it. The hierarchy is implemented as an {% elsif %} chain in Step 4, upgraded to a {% liquid %} block with if / elsif clauses in Step 5. The order matters: 1) Check product.available == false first (Sold Out). 2) Then check tags contains 'sale' (Sale). 3) Then tags contains 'new' (New). 4) Finally tags contains 'custom-badge' with a non-blank metafield (Custom). If you need to change priority — e.g., “New” badges are more important than “Sale” badges for your brand — swap the elsif clauses. The rest of the snippet doesn’t change.

Inventory checks use product.available (a boolean) rather than product.selected_or_first_available_variant.inventory_quantity (an integer). Why? product.available returns false when: total inventory ≤ 0 and “Continue selling when out of stock” is unchecked. This matches the customer-facing behavior — if Shopify won’t let someone add the product to cart, the badge should say “Sold Out.” The integer check (inventory_quantity <= 0) alone doesn’t account for the “continue selling” setting — a product with 0 inventory but “continue selling” enabled is technically purchasable and shouldn’t show a Sold Out badge. For “Low Stock” badges (less than 5 units), use product.selected_or_first_available_variant.inventory_quantity directly — but be aware this returns the first variant’s quantity, not a combined total. For multi-variant products, consider tracking inventory_quantity manually or showing “Low Stock” at the product level only when all variants are low. The snippet doesn’t include low-stock logic by default to keep the production version focused; add it as a {% elsif %} branch before the tag checks.

Liquid conditional flow in this snippet follows a single-assignment pattern: set active_badge and badge_label to empty strings at the top, populate them in priority order via if/elsif, and render exactly one <span> at the end. This pattern avoids the “double badge” bug where a product matches two conditions and outputs two <span> elements stacked on top of each other. The {% if active_badge != '' %} guard at the bottom means products with no matching tags or conditions render nothing — no empty <span>, no stray whitespace, no broken layout. The {% liquid %} wrapper in Step 5 is Shopify’s whitespace-aware multi-line tag: it lets you write multiple if/assign statements without {% %} delimiters on every line, and it automatically strips whitespace between statements. This produces cleaner output — no blank lines in the rendered HTML from Liquid tag formatting.

The snippet parameter API uses Shopify’s {% render %} named parameters. When you call {% render 'product-badge', product: product, position: 'top-right' %}, Shopify creates scoped variables inside the snippet — product is the product object, position is the string 'top-right'. These variables don’t leak into the calling template, so you can name parameters whatever you want without collision. If a parameter is omitted (e.g., no position is passed), the snippet uses the | default: 'top-left' filter to provide a fallback. The badge_class parameter is optional — if omitted, it defaults to an empty string and produces no extra CSS class. The parameter API keeps the snippet generic: the same file works on collection pages (smaller cards, maybe bottom-right position), product pages (larger image, top-left), and featured-product sections (custom styling) — each instance passes different parameters. No copy-paste, no inline modifications.

Create the metafield definition. Go to Settings → Custom data → Products in your Shopify admin. Click Add definition. Name it Badge Text, set the namespace/key to custom.badge_text, and choose type Single line text. This metafield holds the display text for custom badges — “Made in France,” “Best Seller,” “Limited Edition.” Leave it empty on most products; fill it in only on products you also tag with "custom-badge". The metafield is a one-time setup — once the definition exists, every product automatically gets a badge_text field in the admin metafields section.

Add tags to trigger badges. Open any product in Shopify admin, scroll to the Tags field, and add one of these trigger tags: new, sale, or custom-badge. Tag names are lowercase and hyphen-free — new not New, custom-badge not Custom Badge. After saving, preview the product on your storefront. If the snippet is already in place, the badge appears immediately. To test priority: tag a product with both sale and new — the Sale badge should appear (Sale trumps New). Tag a product with sale and set inventory to 0 with “Continue selling” unchecked — the Sold Out badge should appear (Sold Out trumps Sale).

Style badges with CSS. Add these rules to your theme stylesheet. The base product-badge class handles positioning and shared properties. Each modifier class (--sale, --new, --sold-out, --custom) sets the background color. The position classes (top-left, top-right, etc.) override the absolute positioning. All colors use CSS custom properties for easy site-wide theming:

:root {n    --badge-bg-sale: #e74c3c;n    --badge-bg-new: #2ecc71;n    --badge-bg-sold: #95a5a6;n    --badge-bg-custom: #9b59b6;n    --badge-color: #fff;n}nn.product-badge {n    position: absolute;n    z-index: 2;n    padding: 4px 10px;n    border-radius: 3px;n    font-size: 0.75rem;n    font-weight: 700;n    line-height: 1.4;n    color: var(--badge-color);n    white-space: nowrap;n}nn.product-badge--sale     { background: var(--badge-bg-sale); }n.product-badge--new      { background: var(--badge-bg-new); }n.product-badge--sold-out { background: var(--badge-bg-sold); }n.product-badge--custom   { background: var(--badge-bg-custom); }nn.top-left     { top: 10px; left: 10px; }n.top-right    { top: 10px; right: 10px; }n.bottom-left  { bottom: 10px; left: 10px; }n.bottom-right { bottom: 10px; right: 10px; }

The product card’s image wrapper (.product-card__image) needs position: relative for the absolute-positioned badge to anchor correctly. If your theme uses a different class for the image container, adjust the CSS selector accordingly.

Call the snippet from collection and product templates. In sections/main-collection.liquid (or wherever your collection product loop lives), find the product card markup and insert the render call inside the image wrapper:

{% for product in collection.products %}n  <div class="product-card">n    <div class="product-card__image">n      <img src="{{ product.featured_image | image_url }}" alt="{{ product.title | escape }}">n      {% render 'product-badge', product: product %}n    </div>n    <h3>{{ product.title }}</h3>n    <span>{{ product.price | money }}</span>n  </div>n{% endfor %}

On the product page (sections/main-product.liquid), use the same call but with a different position if the image layout differs:

{% render 'product-badge', product: product, position: 'top-right' %}

The snippet is one line per product card — drop it in and the badge logic runs automatically based on tags, metafields, and inventory. No template-specific conditions, no duplicated code.

Custom badge shapes. Replace the rounded-rectangle badge with a diagonal ribbon using CSS transforms:

.product-badge--new {n    width: 120px;n    padding: 6px 0;n    text-align: center;n    transform: rotate(45deg);n    top: 18px;n    right: -30px;n    border-radius: 0;n}

This creates a diagonal corner ribbon effect. For a circular badge (like an app icon), use border-radius: 50% and width: 48px; height: 48px; with centered text via display: flex; align-items: center; justify-content: center;. The HTML stays the same — all shape variations are CSS-only. Use the badge_class parameter to pass a shape modifier class per template: {% render 'product-badge', product: product, badge_class: 'product-badge--ribbon' %}.

Animate badge appearance. Add a CSS keyframe animation that fades and scales the badge in when the product card enters the viewport. Since the badge is rendered server-side and appears immediately, use an animation that activates on page load:

.product-badge {n    animation: badgeAppear 0.3s ease-out both;n}nn@keyframes badgeAppear {n    from {n        opacity: 0;n        transform: scale(0.5);n    }n    to {n        opacity: 1;n        transform: scale(1);n    }n}

For staggered animations on collection pages, add an animation-delay using Liquid’s forloop.index: style="animation-delay: {{ forloop.index | times: 0.05 }}s" on the badge’s <span> tag. Each badge pops in 50ms after the previous one — 20 products animate over 1 second. Add this as a snippet parameter (stagger: true) in the production version for opt-in staggered animation.

Combine badges with sale price display. The Sale badge and the sale price should reinforce each other. Show the regular price with a strikethrough and the sale price next to it — the badge and the price together create a stronger conversion signal than either alone:

{% if product.compare_at_price > product.price %}n  <span class="product-card__price product-card__price--sale">n    <s>{{ product.compare_at_price | money }}</s>n    {{ product.price | money }}n  </span>n{% else %}n  <span class="product-card__price">n    {{ product.price | money }}n  </span>n{% endif %}

The badge and the price display are independent — the badge checks product.tags for the "sale" tag, the price checks product.compare_at_price for a price difference. A product can be on sale (price reduced) without a sale badge if you don’t add the tag. This separation gives editorial control — the marketing team decides which sale products get the badge treatment.

A/B test badge styles. Use Shopify’s built-in A/B testing (or a third-party tool) to test badge variations — color, text, position — without code changes. Add a metafield for the test variant: custom.badge_variant (values: "control" or "variant"). In the snippet, add a conditional class:

{% assign test_class = product.metafields.custom.badge_variant %}n{% if test_class == 'variant' %}n  {% assign badge_class = badge_class | append: ' product-badge--test-variant' %}n{% endif %}

In your CSS, define the variant styles. Track badge click-through rate (clicks to product page from collection) for each variant. The metafield approach lets you assign test groups per product without touching the snippet logic — assign "variant" to half the products, leave "control" on the other half, and split traffic evenly.