> 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/reference/dynamic-variables-reference.md).

# Dynamic variables reference

Complete reference for all dynamic variables you can use in badge and label text content.

Dynamic variables display live product and customer data inside your badge text, replaced with the actual value when a customer views the product.

For example, a badge with the text `Save {sale}!` would display as **Save 25%!** on a product that is 25% off.

## Variable reference table

| Variable                  | Description             | Example output | Plan    |
| ------------------------- | ----------------------- | -------------- | ------- |
| `{product_vendor}`        | Product vendor name     | "Nike"         | FREE    |
| `{product_type}`          | Product type            | "T-Shirt"      | FREE    |
| `{product_sku}`           | Product SKU             | "SKU-12345"    | FREE    |
| `{inventory}`             | Total items in stock    | "42"           | FREE    |
| `{sale}`                  | Discount percentage     | "25%"          | FREE    |
| `{sale_amount}`           | Discount amount         | "$10.00"       | FREE    |
| `{product_variant_count}` | Number of variants      | "3"            | FREE    |
| `{customer_order_total}`  | Customer's total orders | "5"            | FREE    |
| `{customer_spent_total}`  | Customer's total spent  | "$250.00"      | FREE    |
| `{product_metafield}`     | Product metafield value | (varies)       | DIAMOND |
| `{variant_metafield}`     | Variant metafield value | (varies)       | DIAMOND |
| `{countdown}`             | Countdown to end date   | "2d 5h 30m"    | GOLD    |

## Sami discount variables

These four variables read their value from a discount created on the app's [Discounts](/discounts/overview.md) page. In **Insert dynamic text** they are grouped under the **Sami Discount** tab.

| Variable                        | Description                                                                         | Example output |
| ------------------------------- | ----------------------------------------------------------------------------------- | -------------- |
| `{sami_discount_value_percent}` | The discount percentage of the Sami discount applied to the product                 | "20%"          |
| `{sami_discount_value_amount}`  | The discount amount of the Sami discount applied to the product                     | "Save 10.00"   |
| `{sami_discount_code}`          | The discount code of the Sami discount applied to the product (code discounts only) | "SUMMER20"     |
| `{sami_new_price}`              | The product price after the Sami discount is applied                                | "Now 40.00"    |

{% hint style="warning" %}
A Sami discount variable only has a value on a badge scoped to that discount — the badge's **Products** tab must use **Products matching conditions** with the condition **Sami discount** *is equal to* the discount. Saving a discount and clicking **Create badge** sets this up for you.
{% endhint %}

## Notes

{% hint style="info" %}
**Sale variables and auto-hide**\
`{sale}` and `{sale_amount}` support an option to auto-hide the badge when the product isn't on sale, avoiding "0%" or "$0.00" on full-price products.
{% endhint %}

{% hint style="info" %}
**Metafield variables**\
`{product_metafield}` and `{variant_metafield}` require the DIAMOND plan. Selecting one shows a field for the metafield's **namespace and key** — for example, `custom.material` or `custom.care_instructions`. The app pulls that value for each product or variant.
{% endhint %}

{% hint style="info" %}
**Countdown timer**\
`{countdown}` requires the GOLD plan and an **end date** set under **Display > Visibility Date & Countdown** in the badge editor. It updates in real time, showing the remaining time until that date. Choose **Style 1** or **Style 2** in **Insert Dynamic Text** before copying the token.
{% endhint %}

{% hint style="warning" %}
**Variables are case-sensitive** — type them exactly as shown, including the curly braces. `{sale}` works; `{Sale}` or `{SALE}` will not.
{% endhint %}

***

## Next steps

* [Using dynamic variables](/badges-and-labels/dynamic-variables.md) — learn how to add variables to your badge text step by step.
* [Create a text badge](/badges-and-labels/create-text-badge.md) — build your first text-based badge with dynamic content.


---

# 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/reference/dynamic-variables-reference.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.