> 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 appear on product cards across collection pages, search results, and the cart. Three badges fire automatically based on product state; beyond those, you can add up to four custom labels per product using a metafield.

<figure><img src="/files/7DnbE8XwzuqnhH9VvfZ6" alt=""><figcaption></figcaption></figure>

***

### Automatic badges

Avante shows three badges automatically — no setup required:

| Badge         | When it appears                                                |
| ------------- | -------------------------------------------------------------- |
| **Sale**      | Whenever a product has a Compare-at price set in Shopify Admin |
| **Sold out**  | When inventory reaches zero across all variants                |
| **Pre-order** | On products using the `product.preorder` template              |

You can customize the label text and colors for each in **Theme Editor → Theme settings → Product badges**.

<figure><img src="/files/pjwcpVo2sRyIOavZS0kN" alt=""><figcaption></figcaption></figure>

***

### Custom badges

Beyond the automatic three, Avante supports up to 4 custom badge slots per product, each driven by the `custom.badge` metafield.

<figure><img src="/files/BhXEnxFUq5l7BEG1MqK6" alt=""><figcaption></figcaption></figure>

{% 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

<figure><img src="/files/UjiEVEt08vrlvjDcfHng" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Set the type to **List of values**, not single value. This allows multiple badges on one product (e.g., "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

<figure><img src="/files/iElnhmb9GLZ7XHt9ZC2J" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}

#### Step 3 — Register badge names in Theme Editor

1. Go to **Theme Editor → Theme settings → Product badges → Custom badges**
2. In the **Badge 1–4** fields, enter the badge names exactly as entered in the metafield
3. Set text and background colors for each badge
4. Save

<figure><img src="/files/viK8fUmMAkeY5biPzMMx" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
Badge names must match the metafield values exactly — including capitalization and spacing. "New" and "new" are treated as different values.
{% endhint %}
{% endstep %}
{% endstepper %}

{% hint style="success" %}
Use cases: **New**, **Bestseller**, **Limited edition**, **Bundle**, **Staff pick**, **Coming soon** — any label that helps customers make faster decisions.
{% endhint %}

***

### Troubleshooting

<details>

<summary><strong>Custom badge not showing</strong></summary>

The most common cause is a mismatch between the metafield value and the badge name in Theme Settings. Check both for:

* **Exact spelling** — "Bestseller" vs "bestseller" will not match
* **Trailing spaces** — an invisible space at the end of the metafield value breaks the match. Re-enter the value to be sure.
* **Combined values** — entering "New - Bestseller" as a single string won't create two badges. Each badge must be a separate value in the metafield list.

</details>

<details>

<summary><strong>Custom badge disappears when product sells out</strong></summary>

When a product goes out of stock, the **Sold out** badge takes priority and replaces custom badges. This is the theme's default behavior — only one badge displays at a time, with Sold out taking precedence. This is a known limitation.

</details>

<details>

<summary><strong>Sale badge showing after a sale ended</strong></summary>

The Sale badge appears automatically whenever a product has a **Compare-at price** set — regardless of whether a sale is currently active. If the badge is showing unexpectedly, check that Compare-at prices were removed from the products after the sale.

If you want to hide the Sale badge globally without removing 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**.

</details>


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://staylime.com/docs/avante-themes/features-and-advanced-setup/product-badges.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.