> For the complete documentation index, see [llms.txt](https://docs.samita.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.samita.io/badges-and-labels/dynamic-variables.md).

# Use dynamic variables

Reference for dynamic variables that auto-populate text badges with live product and customer data.

Dynamic variables insert live product, inventory, and customer data into your text badges. Instead of writing a static message like "20% Off," use `{sale}` and the badge automatically shows the correct discount percentage for each product.

## Available variables

| Variable                  | Description                                                                      | Example output      |
| ------------------------- | -------------------------------------------------------------------------------- | ------------------- |
| `{sale}`                  | Discount percentage off the compare-at price                                     | 25%                 |
| `{sale_amount}`           | Discount amount off the compare-at price                                         | $10.00              |
| `{inventory}`             | Total items available in inventory                                               | 12                  |
| `{product_vendor}`        | Product vendor                                                                   | Nike                |
| `{product_type}`          | Product type                                                                     | T-Shirt             |
| `{product_sku}`           | Product SKU                                                                      | SKU-12345           |
| `{product_variant_count}` | Number of variants                                                               | 5                   |
| `{customer_order_total}`  | Customer's total order count                                                     | 8                   |
| `{customer_spent_total}`  | Customer's total spend                                                           | $450.00             |
| `{countdown}`             | Countdown based on the visibility date; choose Style 1 or Style 2 before copying | 12Days 20Hrs 50Mins |
| `{product_metafield}`     | Value from a selected product metafield                                          | Organic Cotton      |
| `{variant_metafield}`     | Value from a selected variant metafield                                          | Size EU 42          |

## How to insert a variable

{% stepper %}
{% step %}

## Open a text badge

Create a **Text badge** or open an existing one. In **Design**, expand **Content** and find the **Badge text** editor.

<figure><img src="https://1598842017-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WRTlT5AcaLSAedbCJyZ%2Fuploads%2Fgit-blob-e5f175e31eb496898b6ad037562bbb77e3d6fe14%2Fimage_25.png?alt=media" alt="Choose badge type dialog with Text badge highlighted"><figcaption><p>In Choose badge type, select Text badge to create a badge that supports dynamic variables.</p></figcaption></figure>
{% endstep %}

{% step %}

## Open Insert Dynamic Text

Click **Insert Dynamic Text** in the Badge text toolbar. The **Variables** dialog lists each available token, its sample output, and a **Copy** button.

<figure><img src="https://1598842017-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WRTlT5AcaLSAedbCJyZ%2Fuploads%2Fgit-blob-a5c518c8ee811f809a5026e6997cf2d9c3694092%2Fimage_20.png?alt=media" alt="Insert Dynamic Text button in the Badge text toolbar"><figcaption><p>Click Insert Dynamic Text to open the Variables dialog.</p></figcaption></figure>

<figure><img src="https://1598842017-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WRTlT5AcaLSAedbCJyZ%2Fuploads%2Fgit-blob-85a48b4a0b2a9f16b6926a58d99208783391908a%2Fimage_21.png?alt=media" alt="Variables dialog showing dynamic tokens, sample values, and Copy buttons"><figcaption><p>Review the available variables and their sample output in the Variables dialog.</p></figcaption></figure>
{% endstep %}

{% step %}

## Configure the variable if needed

Most variables are ready to copy immediately. These variables have additional options:

* **Sale variables** — For `{sale}` or `{sale_amount}`, enable the corresponding **Hide label if the product/variant is not on sale** option when the badge should disappear for full-price products.
* **Product or variant metafield** — Expand `{product_metafield}` or `{variant_metafield}`, click **Add metafield**, then select a metafield from the dropdown.
* **Countdown** — Under `{countdown}`, choose **Style 1** or **Style 2** before copying the token.

<figure><img src="https://1598842017-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WRTlT5AcaLSAedbCJyZ%2Fuploads%2Fgit-blob-701040a99ff04882f302795c23463c1818c51488%2Fimage_22.png?alt=media" alt="Expanded product metafield variable with Add metafield, metafield dropdown, and Copy button"><figcaption><p>Add and select the metafield whose value should appear in the badge.</p></figcaption></figure>
{% endstep %}

{% step %}

## Copy and paste the token

Click **Copy** beside the variable. The Variables dialog closes after copying. Click the desired location in the rich text editor, then paste the token into your badge message.

For example, paste `{inventory}` into `Only {inventory} left!` or `{sale}` into `Save {sale}!`.

{% hint style="info" %}
**Copy does not insert the token automatically.** You still need to paste it into the Badge text editor.
{% endhint %}

<figure><img src="https://1598842017-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1WRTlT5AcaLSAedbCJyZ%2Fuploads%2Fgit-blob-c5a417f263123dea795fbd725bbf9edc61ac7315%2Fimage_24.png?alt=media" alt="Dynamic variable token pasted into the Badge text rich text editor"><figcaption><p>Paste the copied token at the position where the live value should appear.</p></figcaption></figure>
{% endstep %}

{% step %}

## Preview and save

Check the badge preview after pasting the token. Configure **Products** and **Display** as needed, choose **Active** or **Draft**, then click **Save**.
{% endstep %}
{% endstepper %}

You can also type a standard token such as `{sale}` or `{inventory}` directly into the editor. Type it exactly as shown, including the curly braces. Use **Insert Dynamic Text** for metafields and countdown styles so the app can generate the correct token.

## Important notes

{% hint style="info" %}
**Sale variables and product visibility:** The `{sale}` and `{sale_amount}` variables include an option to auto-hide the badge when the product isn't on sale. Enable it so the badge only shows on products with a compare-at price higher than the current price.
{% endhint %}

{% hint style="info" %}
**Countdown timer setup:** The countdown variables use the visibility date configured under **Display > Visibility Date & Countdown**.
{% endhint %}

{% hint style="info" %}
**Metafield variables:** Expand the product or variant metafield item in **Insert Dynamic Text**, click **Add metafield**, select a metafield definition, and click **Copy**. Paste the app-generated token instead of typing the generic `{product_metafield}` or `{variant_metafield}` placeholder manually.
{% endhint %}

{% hint style="warning" %}
**Variables are case-sensitive.** Type or paste them exactly as copied, including the curly braces. For example, `{sale}` works, while `{Sale}` and `{SALE}` do not.
{% endhint %}

## Example use cases

Here are some common ways merchants use dynamic variables in their text badges:

| Badge text                                  | What customers see     | Use case                                                   |
| ------------------------------------------- | ---------------------- | ---------------------------------------------------------- |
| Save {sale}!                                | Save 25%!              | Highlight the discount percentage on sale items            |
| Only {inventory} left!                      | Only 3 left!           | Create urgency with low-stock warnings                     |
| Ships from {product\_vendor}                | Ships from Nike        | Show the product vendor for multi-vendor stores            |
| {product\_variant\_count} options available | 5 options available    | Let customers know a product comes in multiple variants    |
| {countdown} left!                           | 2d 05h 30m left!       | Create urgency with a countdown to the end of a sale       |
| VIP: {customer\_order\_total} orders        | VIP: 8 orders          | Reward loyal customers with personalized badges            |
| You have spent {customer\_spent\_total}     | You have spent $450.00 | Show customers their spending history for loyalty programs |

## Next steps

* [Dynamic variables reference](/reference/dynamic-variables-reference.md) — Review the complete variable list and availability notes.
* [Create a text badge](/badges-and-labels/create-text-badge.md) — Build a text badge and insert dynamic variables.
* [Schedule badge visibility](/badges-and-labels/schedule-visibility.md) — Set start and end dates to control when badges appear, and pair with the countdown variable.
* [Target products](/badges-and-labels/target-products.md) — Control which products display each badge using conditions.

{% hint style="success" %}
**Need support?**

If you run into any difficulty while following these steps, contact us at <support@samita.io>.
{% endhint %}


---

# 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://docs.samita.io/badges-and-labels/dynamic-variables.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.