> For the complete documentation index, see [llms.txt](https://staylime.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://staylime.com/docs/avante-themes/features-and-advanced-setup/product-badges.md).
# Product badges
Product badges highlight key product states — Sale, Sold out, Pre-order — and let you add custom labels like "New" or "Bestseller" via a metafield.
Product badges appear on product cards wherever the theme renders them — collection pages, search results, featured collections, recommendations. Three badges fire automatically from the product's state; on top of those you can add your own labels with a metafield.
***
### Automatic badges
Three badges come from the product itself:
| Badge | When it appears |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Sale** | The product is in stock and the selected variant has a Compare-at price higher than its price |
| **Sold out** | The product is unavailable — nothing left in stock on any variant |
| **Pre-order** | The product uses the `product.preorder` template **and** **Show product pre-order badge** is on in **Theme settings → Product card** |
{% hint style="warning" %}
**The badge wording is not in Theme settings.** **Theme settings → Product badges** sets colors and the Sale badge style — there are no text fields for "Sale", "Sold out" or "Pre-order" there. To reword them, go to **Shopify Admin → Content → Translations** (or use the Translate & Adapt app) and edit the theme strings.
{% endhint %}
The Sale badge has a **Badge style** setting in **Theme settings → Product badges**: **Text** shows the Sale wording, **Percentage** replaces it with the discount calculated from the Compare-at price, prefixed with a minus — for example `-20%`. The figure is rounded to a whole number; discounts under half a percent keep one decimal instead of rounding down to zero.
***
### Badges can appear together
There is no "one badge at a time" rule. A card renders every badge that qualifies, in this order: custom badges from the variant, custom badges from the product, Sale, Sold out, Pre-order.
What decides the combination is stock:
* **In stock** — custom badges and Sale can show side by side, with Pre-order on top of them if the product uses the pre-order template.
* **Out of stock** — custom badges and Sale are not rendered at all. Only Sold out remains, plus Pre-order if it applies.
So a sold-out product losing its "Bestseller" badge is expected behaviour, not a conflict between badges.
***
### Custom badges
Custom badges are driven by the `custom.badge` metafield. Any value you put in the list is displayed — the theme does not cap how many badges a product can show.
{% stepper %}
{% step %}
#### Step 1 — Create the metafield definition
1. Go to **Shopify Admin → Settings → Metafields and metaobjects → Products**
2. Click **Add definition**
3. Fill in:
* **Name:** Badge
* **Namespace and key:** `custom.badge`
* **Type:** Single line text — List of values
4. Save
{% hint style="warning" %}
Set the type to **List of values**, not single value. That is what lets one product carry several badges — "New" and "Bestseller" at the same time.
{% endhint %}
{% endstep %}
{% step %}
#### Step 2 — Add badges to products
1. Open a product in Shopify Admin
2. Scroll down to **Metafields**
3. Find **Badge** and enter each badge name as a separate value
4. Save
{% endstep %}
{% step %}
#### Step 3 — Give the badges their colors
1. Go to **Theme Editor → Theme settings → Product badges → Custom badges**
2. In **Badge 1–4**, type the badge names you used in the metafield
3. Set a text and background color for each
4. Save
{% endstep %}
{% endstepper %}
{% hint style="info" %}
**Badge 1–4 are color slots, not a limit on badges.** A product can carry more than four values in the metafield and all of them appear. Values that don't match any of the four names are still shown — they just fall back to the theme's default dark badge instead of a color of your choosing.
{% endhint %}
{% hint style="success" %}
**Capitalization doesn't matter.** The theme compares the metafield value and the Badge name in lower case, so `New`, `new` and `NEW` all match the same slot. Spelling and spacing still have to line up.
{% endhint %}
{% hint style="success" icon="sparkles" %}
Use cases: **New**, **Bestseller**, **Limited edition**, **Bundle**, **Staff pick**, **Coming soon** — any label that helps customers decide faster.
{% endhint %}
***
### Badges on a single variant
The theme reads `custom.badge` from the variant as well as from the product. Define the same metafield on **Variants** instead of Products, fill it in on one variant, and the badge appears only while that variant is the one selected on the card.
Both sources are rendered, so a product-level "Bestseller" and a variant-level "Low stock" will show together rather than replacing one another.
***
### Troubleshooting
Custom badge not showing
* **The product is out of stock** — custom badges are hidden on unavailable products by design. Only Sold out and Pre-order survive.
* **Spelling or spacing** — the colors are matched by name, so "Best seller" and "Bestseller" land in different slots. Capitalization is not the problem; the comparison ignores it.
* **Trailing spaces** — an invisible space at the end of a metafield value breaks the colour match. Re-enter the value to be sure.
* **Combined values** — "New - Bestseller" as one string is one badge, not two. Each badge has to be its own value in the list.
If a badge shows but is plain dark rather than your color, the badge itself is fine — only the name in **Badge 1–4** doesn't match.
Sale badge showing after a sale ended
The Sale badge appears automatically whenever a variant has a **Compare-at price** above its price — whether or not you think of it as a sale. If the badge shows unexpectedly, check that Compare-at prices were cleared after the sale.
To hide the Sale badge globally without touching Compare-at prices, add this to **Theme settings → Custom CSS**:
```css
.card__badges-item--sale {
display: none;
}
```
To hide it on collection pages only, add the same snippet to **Theme Editor → Collection page → Collection page section → Custom CSS**.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/product-badges.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
.png?alt=media&token=b887c209-b658-4544-82a1-1706afe02764)
.png?alt=media&token=51c8adbd-52cd-49c7-a4c7-5dcca7ec6565)
.png?alt=media&token=1fc8875d-09ae-466c-b091-dc00101d3c23)
.jpg?alt=media&token=48b6ce61-6d5f-445e-99b0-e1a1f67a6662)
.jpg?alt=media&token=30fc62dc-e55c-412b-bda9-8b1a23419d1c)
.png?alt=media&token=5995337c-77f2-403a-aba0-b37953c9eeea)