# discountkit — full documentation

> The discounting platform for Shopify. This file concatenates every documentation page; canonical URLs are noted per section.

---

# DiscountKit documentation

Source: https://discountkit.app/docs/

DiscountKit runs every promotion you can imagine: pick a discount type, set
the rules, and it runs everywhere — cart, checkout, and your storefront.

Every section is here — discount types, DiscountKit Live, the component
reference, and help guides. Use the sidebar or search to find what you need.

## DiscountKit Live

Your discount data, published straight to storefront metafields — no API
calls, no performance overhead.

    title="Introduction"
    description="How Live works: the dk:live tag, sync, limits and fan-out."
    href="/docs/live/introduction/"
  />
    title="Storefront data"
    description="Reading discounts from product, collection and shop metafields."
    href="/docs/live/storefront-data/"
  />

## Coming to these docs

Discount types (volume, tiered, gift with purchase, order goals, custom
rules), Live web components (`<dkl-price>`, `<dkl-discount-badge>`,
`<dkl-order-goal>`), Sidekick, POS, and test mode.

---

# AI tools (MCP)

Source: https://discountkit.app/docs/ai-tools/

The discountkit documentation is available as a remote [MCP](https://modelcontextprotocol.io) server, so your AI editor can search and read these docs directly. No install, no API key — it runs on the same edge deployment as this site.

**Endpoint:** `https://discountkit.app/mcp` (streamable HTTP)

## Setup

    ```bash
    claude mcp add --transport http discountkit-docs https://discountkit.app/mcp
    ```
    Add to `.cursor/mcp.json`:
    ```json
    {
      "mcpServers": {
        "discountkit-docs": { "url": "https://discountkit.app/mcp" }
      }
    }
    ```
    Any MCP client with streamable HTTP support can connect to the endpoint directly. For stdio-only clients, bridge with:
    ```bash
    npx -y mcp-remote https://discountkit.app/mcp
    ```

## Tools

| Tool | What it does |
| --- | --- |
| `search_docs` | Ranked search across every docs page, with snippets and URLs |
| `get_doc` | One page as full markdown, by path |
| `list_docs` | Every page with title, description and URL |

The machine-readable catalog lives at [`/mcp-schema.json`](/mcp-schema.json). Prefer plain files? The whole documentation set is also published at [`/llms.txt`](/llms.txt) and [`/llms-full.txt`](/llms-full.txt).

---

# App blocks vs. Web Components

Source: https://discountkit.app/docs/components/app-blocks-vs-web-components/

Every Live Component can be placed two ways. They render the **same component**
from the **same data** — the difference is who places it, how it's configured, and where
it's allowed to go.

- **App blocks** — added through the **theme editor**. No code; every setting is a control
  in the editor. The right choice for most merchants, and the only way to render inside
  **product cards** on collection pages.
- **Web Components** — the `<dkl-*>` element written **directly into your theme's
  Liquid**. Configured with `data-*` attributes and `--dkl-*` CSS. For developers
  customizing a theme by hand. (These are labelled "Web Components" on each component page.)

## At a glance

| | App block | Web Component |
| --- | --- | --- |
| **Added by** | Theme editor (drag-and-drop) | Hand-written in theme Liquid/HTML |
| **Configuration** | Editor settings panel | `data-*` attributes |
| **Styling** | Editor pickers (colours, spacing, fonts) | `--dkl-*` CSS styling tokens |
| **Which discount** | The block's **Discount** picker | `data-discount-id` attribute |
| **Product cards / collection grids** | ✅ Supported | ❌ Product-page only |
| **Needs the app embed** | ✅ Yes | ✅ Yes |
| **No-flicker render** | ✅ Inline server render | ✅ From a head carrier |
| **Best for** | Merchants, no code | Developers, full control |

:::note
Both paths require the **Discount Kit Live** app embed to be enabled — it loads the shared
runtime (styles + behaviour) and pre-renders the data each component reads. See
[Enable the Global App Embed](/docs/components/overview/#enable-the-discount-kit-live-app-embed).
:::

## App blocks

An app block is a theme block you add in the editor — **DK: Price**, **DK: Volume Groups**,
**DK: Discount Badge**, or **DK: Order Goal**. Drop it into a section or product-card slot,
and configure it entirely through the editor's settings panel.

```text
Online Store → Themes → Customize → (add block) → DK: Price
```

What an app block does for you:

- **Resolves the eligible discount itself** — using the shared eligibility rules, so it
  agrees with the custom-tag path. When more than one discount applies, it renders the
  first eligible one, or a specific one chosen in its **Discount** picker setting.
- **Exposes every option as an editor control** — colours, spacing, labels, and
  behaviour toggles. Your choices are written into a scoped `<style>` rule the block emits,
  so styling lives in the theme editor.
- **Only loads when it's on the page** — its stylesheet and controller load with the block.
- **Reaches contexts a tag can't** — most importantly **product cards** in a collection
  grid, where there's no single product in `<head>` context to pre-stage a carrier from.

Use an app block when a merchant should be able to place and style the component without
touching code, or whenever you need it inside a product card.

## Web Components

A web component is the `<dkl-*>` web component written straight into your theme's
markup:

```html
<dkl-price></dkl-price>
```

By default, a web component needs **zero attributes** — the page's primary product is the
implicit default, and the tag clones a pre-staged carrier (markup, styling, and `data-*`
values) before first paint. Configure it with `data-*` attributes and style it with
`--dkl-*` CSS:

```html
<dkl-price
  data-show-savings="true"
  style="--dkl-price-savings-background:#111; --dkl-price-savings-color:#fff"
></dkl-price>
```

What to know about web components:

- **Product-page only.** Carriers exist only where there's a single product (or the shop)
  in context. A collection grid is paginated and per-product, so a hand-typed tag can't be
  pre-staged there — use the app block for product cards.
- **Target a specific discount** with `data-discount-id` (the metaobject handle; the
  `discount-` prefix is optional). Place one tag per discount to show several.
- **Style with `--dkl-*` tokens** in your own CSS — a tag has no block context, so there's
  no editor panel. Set the tokens on `:root`, the embed's Custom CSS, an inline `style`, or
  any ancestor. The defaults match the app block exactly, so an unstyled tag looks identical
  to a default block.
- **Behaviour toggles may default off.** For the volume picker, native-price update and
  quantity sync only run if you opt in (`data-update-price-on-change="true"` /
  `data-sync-with-quantity="true"`); any attribute you set wins over the carrier's.

Use a web component when you're editing the theme directly and want precise control over
placement, attributes, and CSS.

## Which should I use?

    The merchant should configure it without code · you need it in a **product card** ·
    you want styling managed from the theme editor.
    You're editing theme Liquid directly · you want exact control over placement and
    `data-*` · you're styling with `--dkl-*` CSS · you need several discounts placed by hand.

## Next steps

---

# App block

Source: https://discountkit.app/docs/components/discount-badge/app-block/

The **DK: Discount Badge** app block renders `<dkl-discount-badge>` with no code — you add
it in the theme editor and configure every option through its settings panel. It resolves to
the product in context, reads the [`max_reward_*` metafields](/docs/live/reference/) itself, and
server-renders the correct badge.

:::note
The app block is the **only** way to render a badge in collection **product cards**. A custom
element can't, because carriers exist only where there's a single product in context — a
product grid has many. Add the block to the product-card slot to cover the whole grid,
pagination included.
:::

## Add the block

1. **Open the theme editor**

   In the Shopify admin, go to **Online Store → Themes** and click **Customize**. Make sure the **Discount Kit Live**
   app embed is enabled.

2. **Add DK: Discount Badge**

   For **product cards**, add the **DK: Discount Badge** block to the theme's product-card slot — it then renders
   on the card's product across every page, pagination included. For a **product page**, switch the top template
   selector to a **Product** template, then add the block where the badge should appear.

## Settings

Every setting maps to a `data-*` attribute or `--dkl-badge-*` token under the hood — see
[Styling & Data Attributes](/docs/components/discount-badge/styling-and-data/) for the equivalents.

### Content

#### `Discount type to show`

`select` · default: `Percentage`

Which amount to show — **Percentage** (e.g. 20%), **Fixed amount** (e.g. $5.00), or
**Highest amount** (whichever saves more).

#### `Label`

`text` · default: `Save up to [amount]`

Label template. Use `[amount]` for the discount value.

### Style

#### `Margin top`

`range` · default: `0px`

Space above the badge, 0–80px.

#### `Margin bottom`

`range` · default: `0px`

Space below the badge, 0–80px.

#### `Background color`

`color` · default: `var(--dkl-color-accent)`

Badge background. Defaults to the accent brand colour.

#### `Text color`

`color` · default: `#ffffff`

Badge text. Defaults to white.

#### `Corner radius`

`range` · default: `8px`

Badge corners, 0–24px.

#### `Vertical padding`

`range` · default: `3px`

Vertical padding, 0–32px.

#### `Horizontal padding`

`range` · default: `8px`

Horizontal padding, 0–48px.

#### `Font size`

`range` · default: `14px`

Badge text size, 8–48px.

#### `Font size (mobile)`

`range` · default: `10px`

Badge text size on mobile, 8–48px.

#### `Font weight`

`range` · default: `600`

Badge text weight, 100–900. Font weights may be limited to your theme's installed font files.

:::note
Colour, radius, spacing, and font pickers are written into a scoped `<style>` rule the block
emits, so they live-update in the theme editor and stay overridable by your own CSS.
:::

## Next steps

---

# Events

Source: https://discountkit.app/docs/components/discount-badge/events/

`<dkl-discount-badge>` is otherwise standalone — it has no discount or state event of its own
(it reads the product's max-reward metafields server-side and re-renders on variant change).
What it does emit are **lifecycle** events as its behaviour attaches and tears down.

## Emits

Each badge instance emits **mount** and **unmount** events — handy for wiring up (and cleaning
up) custom integrations per instance. Both **bubble** and carry a `DklWidgetEventDetail`
resource.

#### `discount-kit-live:widget:mount`

`CustomEvent`

Fired once the controller has attached its behaviour to the (already server-rendered)
element. `resource`: `{ widgetType, widgetId, productId? }` — `productId` is included when
known.

#### `discount-kit-live:widget:unmount`

`CustomEvent`

Fired when the instance tears down — e.g. the element is removed, or the theme editor
re-renders the section. Same `resource` shape. Use it to detach any listeners or observers
you set up on mount.

```js
// event.detail.resource on widget:mount / widget:unmount
{
  widgetType: 'discount-badge',
  widgetId: null,
  productId: 7820000000001
}
```

:::tip
To react to the badge's **text** changing (e.g. on a variant change), there's no event —
observe the element with a `MutationObserver` instead. See
[Reacting to changes](/docs/components/discount-badge/web-component/#reacting-to-changes).
:::

## Next steps

---

# Discount Badge

Source: https://discountkit.app/docs/components/discount-badge/overview/

![DKL Discount Badge component](/images/components/dkl-discount-badge-component.jpg)

*DKL Discount Badge component*

`<dkl-discount-badge>` is a theme-agnostic "max discount" badge — e.g. **Save up to 20%**
or **Save up to $5.00**. It's a **light-DOM** component: the label is the element's own
text content (no shadow DOM), and the host element itself is styled as the badge. That
keeps it dropping cleanly into a product card and painting from server-rendered markup.

The amount comes from the product's [`max_reward_percent` / `max_reward_cents` metafields](/docs/live/reference/):

- `max_reward_percent` — a decimal percent, rounded to a whole number (`19.6 → 20%`);
- `max_reward_cents` — an integer, formatted as money via the shop's money format.

Which one shows is chosen by `data-discount-type` — the percent, the cents, or **highest**
(whichever saves more). The visible text is server-rendered, so it paints immediately; the
component is an optional enhancement that re-composes the label and re-picks the `highest`
option on a variant change.

## On this component

:::note
Both placements need the **Discount Kit Live** app embed enabled, and render identically —
the same defaults back both. See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/)
for how to choose.
:::

:::note
The badge is otherwise **standalone** — it reads the product metafields server-side and
re-picks the `highest` option on the host theme's variant-change events. It emits no
discount/state event of its own, only the [mount / unmount lifecycle events](/docs/components/discount-badge/events/).
:::

## Accessibility

- **Real text.** The badge is plain, server-rendered text (e.g. "Save up to 20%") — not an
  image or a CSS background — so screen readers read it verbatim and it scales with browser
  zoom and text-size settings.
- **No empty announcements.** When nothing applies, the component hides the host entirely
  rather than leaving an empty element for assistive tech to encounter.
- **Contrast.** Because the badge colours are merchant-configurable, keep `--dkl-badge-color`
  and `--dkl-badge-background` at a sufficient contrast ratio when restyling.

---

# Styling & Data Attributes

Source: https://discountkit.app/docs/components/discount-badge/styling-and-data/

This is the shared reference for `<dkl-discount-badge>` — the `data-*` attributes that drive
its behaviour and the `--dkl-badge-*` tokens that style it. The [app
block](/docs/components/discount-badge/app-block/) settings map onto these; on a [web component](/docs/components/discount-badge/web-component/)
you set them directly.

:::note[Using this reference with the app block]
When you place the [**DK: Discount Badge** app block](/docs/components/discount-badge/app-block/), it
renders its own `<dkl-discount-badge>` and writes these values for you — so what applies depends
on the kind of override:

**Data attributes — No:**
The block sets every `data-*` itself, from its App block settings and the resolved discount. Adding `data-*` to your own markup has no effect on a block instance; they're the configuration surface for the [web component](/docs/components/discount-badge/web-component/) only. To change block behaviour, use its [settings](/docs/components/discount-badge/app-block/).

**CSS styling tokens — Yes:**
They're CSS custom properties that inherit through to the host, so they style a block exactly like a web component. The block's colour / radius / spacing / font pickers just write the matching tokens into a scoped `<style>` rule for you. Any token **not** exposed as a setting you can still set yourself from your own CSS — `:root`, the embed's **Custom CSS** field, or a rule targeting the block.

This component is **light-DOM, host-only** — the host element *is* the badge. There's no shadow DOM, so there are **no CSS parts**: style the host element directly (`dkl-discount-badge { … }`).
:::

:::tip[Token precedence]
A token the block writes from a chosen setting is scoped to the block's id (`#dkl-badge-{block.id}`),
which is more specific than a `:root` rule — so to override *that* token, either change the editor
setting or match the specificity (target the block element). Tokens the block leaves unset fall back to your CSS or
the built-in default as normal.
:::

## Data attributes

All optional — the carrier (or your own Liquid) supplies them. Set one to override.

#### `data-discount-type`

`"percentage" | "fixed" | "highest"` · default: `percentage`

Which amount to show — the percent, the cents, or **whichever saves more**. `highest` is
computed against the current variant price (`percent × price` vs the fixed cents); ties
favour the percentage, and a missing side falls back to the other.

#### `data-amount-percent`

`number (decimal percent)` · default: `carrier (max_reward_percent)`

The percentage amount (rounded for display).

#### `data-amount-cents`

`int (cents)` · default: `carrier (max_reward_cents)`

The fixed amount (money-formatted).

#### `data-base-price-cents`

`int (cents)` · default: `carrier (the variant's price)`

The variant price; drives the `highest` comparison (recomputed on variant change).

#### `data-money-format`

`string` · default: `carrier (shop.money_format)`

Money format for the `fixed` amount.

#### `data-label`

`string` · default: `Save up to [amount]`

Label template; `[amount]` is replaced with the formatted amount.

:::note
The component **hides** the host only when it can compute that there's nothing to show and
there's no server-rendered text already. Without the `data-*` attributes it leaves the
server text alone.
:::

## CSS styling tokens

![Image highlighting the CSS styling tokens for the DKL Discount Badge component](/images/components/dkl-discount-badge-css-tokens.jpg)

*CSS styling tokens for the DKL Discount Badge component*

The stylesheet (loaded site-wide by the embed) styles the **host element** directly — the
host *is* the badge, so target `dkl-discount-badge { … }` (there are no CSS parts). Set any
token above the element — `:root`, the embed's Custom CSS, an inline `style`, or the block's
scoped rule.

#### `--dkl-badge-background`

default: `var(--dkl-color-accent)`

Badge background.

#### `--dkl-badge-color`

default: `#ffffff`

Badge text.

#### `--dkl-badge-radius`

default: `var(--dkl-radius)`

Badge corners.

#### `--dkl-badge-padding-block`

default: `0.175rem`

Vertical padding.

#### `--dkl-badge-padding-inline`

default: `0.5rem`

Horizontal padding.

#### `--dkl-badge-font-size`

default: `0.75rem`

Badge text size.

#### `--dkl-badge-font-weight`

default: `600`

Badge text weight.

The **DK: Discount Badge** block exposes Background color, Text color, Corner radius,
Vertical / Horizontal padding, Font size, and Font weight settings that feed the matching
tokens via a scoped `<style>` rule.

## Examples

```html title="Restyle a single badge inline"
<dkl-discount-badge
  style="
    --dkl-badge-background: #111;
    --dkl-badge-color: #fff;
    --dkl-badge-radius: 999px;
    --dkl-badge-font-size: 0.85rem;
    --dkl-badge-font-weight: 700;
  "
></dkl-discount-badge>
```

```css title="Style the host via :root tokens"
:root {
  --dkl-badge-background: #111;
  --dkl-badge-color: #fff;
  --dkl-badge-radius: 999px;
}
```

```css title="Target the host element directly"
dkl-discount-badge {
  letter-spacing: 0.02em;
  text-transform: uppercase;
}
```

## Next steps

---

# Web Component

Source: https://discountkit.app/docs/components/discount-badge/web-component/

A web component is the `<dkl-discount-badge>` tag written directly into your theme's Liquid.
On a **product page** it needs **zero attributes** — it paints from the page product's carrier
and renders the badge.

## Usage

On a product page, add the `<dkl-discount-badge>` web component — it renders the primary product's badge:

```html
<dkl-discount-badge></dkl-discount-badge>
```

:::caution[Beta Limitation for Web Components: Single Product Context]
During beta of the DKL Live Components, a Web Component is only recommended for product
pages / where the products shown on the page are static on page load.

A Web Component paints from a server-rendered **carrier**, which the `dkl_core` embed
pre-renders only on **product pages**, and only for that page's product. So a Web Component
**can't render on a collection page** — no carriers are emitted there at all (each card is a
different product) — nor for product instances loaded in **after** page load via the Section
Rendering API / Ajax. For **product cards** and these cases, use the
[app block](/docs/components/discount-badge/app-block/) instead, which renders inline per card
(resolving each card's own product). See
[App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/).
:::

## Reacting to changes

`<dkl-discount-badge>` emits no events — it re-renders its own text in place on a variant
change. To run your own code when the badge updates, watch the element with a
`MutationObserver` — see [React to badge updates](#examples) in the examples below.

## Examples

For the full list of `data-*` attributes you can set, see
[Styling & Data Attributes](/docs/components/discount-badge/styling-and-data/).

```html title="Whichever discount saves more"
<dkl-discount-badge data-discount-type="highest"></dkl-discount-badge>
```

```html title="Override attributes + tokens"
<dkl-discount-badge
  data-discount-type="highest"
  data-label="[amount] off today"
  style="
    --dkl-badge-background: #111;
    --dkl-badge-color: #fff;
    --dkl-badge-radius: 999px;
    --dkl-badge-font-size: 0.85rem;
  "
></dkl-discount-badge>
```

```js title="React to badge updates"
// <dkl-discount-badge> emits no events — it re-renders its own text in place
// on variant change. Observe each badge to react to those updates.
// Handles any number of badges on the page.
document.querySelectorAll('dkl-discount-badge').forEach((badge) => {
  new MutationObserver(() => {
    console.log('Badge now reads:', badge.textContent.trim())
  }).observe(badge, { childList: true, characterData: true, subtree: true })
})
```

## Next steps

---

# Styling

Source: https://discountkit.app/docs/components/global-styling/

All component styling is driven by `--dkl-*` **CSS styling tokens** (CSS custom properties),
each with a built-in fallback. There are two layers:

- **Global brand tokens** (`--dkl-color-*`, `--dkl-radius`, `--dkl-font-family`) — shared by
  every component, so setting one re-themes all of them at once.
- **Per-component tokens** (`--dkl-price-*`, `--dkl-vp-*`, `--dkl-badge-*`, `--dkl-og-*`) — fine
  control over a single component; documented on each component's **Styling & data** page.

Because tokens inherit through the shadow boundary, you can set them anywhere above a
component — the embed's **Custom CSS** field, a `:root` rule in your theme stylesheet, an
inline `style` on the tag, or the scoped rule an app block emits.

```css
/* e.g. in the embed's Custom CSS field, or your theme stylesheet */
:root {
  --dkl-color-accent: #6d28d9;
  --dkl-radius: 12px;
  --dkl-price-sale-color: #c0392b;
}
```

## Global brand tokens

The embed emits these on `:root`. They back every component, and each component's own
`--dkl-<widget>-*` tokens take precedence over them for fine-grained control.

#### `--dkl-font-family`

default: `inherit`

Component font family. Custom font families must be installed on the theme.

#### `--dkl-color-text`

Default text colour.

#### `--dkl-color-accent`

Accent / selected state.

#### `--dkl-color-success`

Success / savings colour.

#### `--dkl-color-border`

Border colour.

#### `--dkl-radius`

Corner radius for all components.

## Per-component style tokens

Each component adds its own tokens (and, where relevant, CSS parts and light-DOM classes) on
top of the global ones. See its **Styling & data** page for the full list:

## App block vs. web component

:::note
Inside an **app block**, the editor's styling settings are written into a scoped `<style>`
rule the block emits — so merchants style it entirely from the theme editor. A **web component**
has no block context, so you style it by setting the same `--dkl-*` tokens in your own
CSS. Every token has the same default in both places, so a web component with no
overrides looks identical to a default app block.
:::

## Targeting structural elements

Tokens cover colours, sizes, and spacing. For anything structural, components expose two
mechanisms depending on where the element lives:

- **Shadow-DOM elements** are reached with [`::part(name)`](https://developer.mozilla.org/docs/Web/CSS/::part)
  from any rule — parts pierce the shadow boundary. You can add states (`::part(price):hover`)
  but cannot descend into a part (`::part(price) span` does not work).
- **Light-DOM elements** are reached with their **class**, like any other markup. They're
  already styled by the component's stylesheet, so override by matching the class and winning
  on specificity (or, preferably, use a token where one exists).

Each component's **Styling & data** page lists the parts and classes it exposes.

:::note[Money formatting]
The price and volume picker reformat prices in JavaScript as tiers and
variants change. To stay byte-identical to your server-rendered Liquid `money` filter, each
carrier passes `shop.money_format` down as `data-money-format`, which the components render with
— avoiding the locale-dependent currency prefixes (e.g. `US$`) that `Intl` would otherwise
produce.
:::

---

# Live Data & Live Components

Source: https://discountkit.app/docs/components/live-data-live-components/

Discount Kit Live comes in two flavours, built on the **same foundation**: you opt a discount
in by tagging it `dk:live`, and Discount Kit syncs it to your storefront. Live Components are a set of pre-built UI components that you can drop into your storefront, and Live Data is the data that powers those components. Our new components are the easiest way to surface discount data in your storefront.

- **Live Data** — a **data layer**. Your synced discounts are exposed through storefront
  [metafields](/docs/live/storefront-data/), and **you build the UI yourself in Liquid** (badges,
  strike-through pricing, banners, gift selectors…). Maximum flexibility; you write the markup.
- **Live Components** — **drop-in [web components](/docs/components/overview/)**. The same discounts are
  rendered for you by `<dkl-*>` elements and theme app blocks — a price, a volume picker, a
  badge, an order-goal bar. Little or no code; themeable through `--dkl-*` tokens.

The primary difference between how you use Live Data and Live Components is that Live Components don't require you to manually loop through the data, handle discount conditions etc - we take care of that for you and you simply drop in the components where you want them.

:::note
Both require the discount to be tagged `dk:live` and synced. See the
[Live introduction](/docs/live/introduction/) for how syncing works.
:::

## At a glance

| | Live Data | Live Components |
| --- | --- | --- |
| **What it is** | Discount data in metafields | Pre-built UI components |
| **How you use it** | Read metafields in your theme's Liquid | Add an app block, or drop in a `<dkl-*>` tag |
| **Code required** | You write the markup | None (app block) to minimal (web component) |
| **Flexibility** | Total — any UI you can build | A fixed set of components, themed with tokens |
| **Styling** | Your own CSS | `--dkl-*` [styling tokens](/docs/components/global-styling/) + editor settings |
| **Best for** | Bespoke layouts, custom logic | Standard widgets, fast setup, no-code merchants |

## Server Side Rendering

One of the key decisions when creating Discount Kit Live was to allow merchants and developers to surface discount data server side - no flicker on your component while JS loads, no complex fetching of data via the Storefront API, just simple data models that can be accessed via Shopify's native language, liquid.

Live Components are no different and have been carefully architected to combine the simplicity of a conventional web component with the benefits of server side rendering, whilst still allowing you to customise the UI's to your needs through a dedicated styling and data API.

## Use them together

Live Data and Live Components are **not mutually exclusive** — they read the same `dk:live` discounts, so you can
mix them on the same store (even the same page):

- Use **Live Components** for the standard widgets (price, volume picker, badge, order goal).
- Keep **Live Data** for anything bespoke a component doesn't cover — a custom
  collection banner, a gift-selector, store-specific logic.

Enabling the **Discount Kit Live app embed** (which powers Live Components) does not affect your Live Data
metafields — your existing Liquid keeps working exactly as before.

## Which should I use?

:::note
The Live Components are currently in **beta**. The Live Data API is stable and unaffected.
:::

---

# App block

Source: https://discountkit.app/docs/components/order-goal/app-block/

The **DK: Order Goal** app block renders `<dkl-order-goal>` with no code — you add it in the
theme editor and configure every option through its settings panel. It renders one order-goal
discount: the one chosen in its **Discount** picker, or the first eligible discount in the
shop feed when the picker is left empty.

## Add the block

1. **Open the theme editor**

   In the Shopify admin, go to **Online Store → Themes** and click **Customize**. Make sure
   the **Discount Kit Live** app embed is enabled.

2. **Add the DK: Order Goal block**

   In the section where you want the progress bar — for example the cart, or a product page —
   click **Add block** and choose **DK: Order Goal**, then position it where the bar should
   appear.

## Settings

Every setting maps to a `data-*` attribute or `--dkl-og-*` token under the hood — see
[Styling & Data Attributes](/docs/components/order-goal/styling-and-data/) for the equivalents.

### Discount & layout

#### `Discount`

`metaobject`

Show only this order goal discount. Leave empty to show the first one.

#### `Layout`

`select` · default: `Horizontal`

**Horizontal**, or **Stacked** (markers in a column, progress bar rotated).

### Content

#### `Spend-more message`

`text` · default: `Spend [amount] more to save [discount] on your order!`

Shown until every tier is met. Use `[amount]` for the amount to the next tier and
`[discount]` for its discount.

#### `Success heading`

`text` · default: `Winner Winner 🎉`

Heading shown once every tier is met.

#### `Success message`

`text` · default: `You've unlocked all available savings`

Body shown once every tier is met.

#### `Tier label`

`text` · default: `Save [discount]`

Use `[discount]` for the tier's discount.

#### `Tier spend label`

`text` · default: `when you spend [amount]+`

Use `[amount]` for the tier's minimum spend.

### Spacing & sizing

#### `Margin top`

`range` · default: `0px`

Space above the widget, 0–80px.

#### `Margin bottom`

`range` · default: `0px`

Space below the widget, 0–80px.

#### `Padding`

`range` · default: `16px`

Inner padding of the card, 0–48px.

#### `Font sizing`

`select` · default: `Inherit (theme)`

**Inherit**, or **Custom**. The two font-size settings below apply only when set to Custom.

#### `Font size (desktop)`

`range` · default: `16px`

Desktop font size, 10–32px. Custom only.

#### `Font size (mobile)`

`range` · default: `14px`

Mobile font size, 8–28px. Custom only.

#### `Border radius`

`range` · default: `8px`

Card corners, 0–24px.

### Colors

#### `Progress bar color`

`color` · default: `#217a4a`

The progress fill.

#### `Track color`

`color` · default: `#e5e5e5`

The unfilled progress track behind the fill.

#### `Background color`

`color` · default: `#f7f7f7`

Card background.

#### `Text color`

`color` · default: `#1a1a1a`

The headline / progress message.

#### `Tier label color`

`color` · default: `#1a1a1a`

The per-tier "Save [discount]" line.

#### `Tier spend label color`

`color` · default: `#737373`

The per-tier "when you spend [amount]+" line.

#### `Icon background: not met`

`color` · default: `#ffffff`

Marker background for tiers not yet met.

#### `Icon background: met`

`color` · default: `#217a4a`

Marker background for met tiers.

### Icons

#### `Percentage discount icon`

`image`

Swaps the marker glyph for a custom image on percentage-discount tiers.

#### `Fixed amount icon`

`image`

Swaps the marker glyph for a custom image on fixed-amount tiers.

#### `Tier met icon`

`image`

Swaps the marker glyph for a custom image once a tier is met.

:::note
These icon images are an app-block-only feature — a [web component](/docs/components/order-goal/web-component/)
would set the marker glyph via CSS instead (the `--dkl-og-icon` mask).
:::

## Next steps

---

# Events

Source: https://discountkit.app/docs/components/order-goal/events/

`<dkl-order-goal>` recomputes its progress on every cart update and emits a single custom
event when the cart total crosses a tier boundary. To run your own logic on a tier change,
listen for it — see [Reacting to changes](/docs/components/order-goal/web-component/#reacting-to-changes)
and the examples on the [web component](/docs/components/order-goal/web-component/#examples) page.

## Emits

:::note[`widgetId`]
The **app block's id** — `null` on a web component. `discountId` identifies which order goal a
concurrent instance tracks.
:::

#### `discount-kit-live:order-goal:tier-change`

`CustomEvent`

Fired when the cart total crosses a tier boundary. The initial render establishes the
baseline silently — the event fires only on a subsequent change, in either direction
(unlocking a tier, or dropping below one when items are removed). The detail carries
`resource`:

```ts
resource: {
  widgetId: string | null
  widgetType: 'order-goal'
  discountId: string
  previousTier: OrderGoalTier | null
  currentTier: OrderGoalTier | null
  cartTotalCents: number
}

// previousTier / currentTier are null below the first tier
type OrderGoalTier = {
  tierLevel: number
  minSpendCents: number
  discountAmount: number     // raw config value: percent, or CENTS for fixedAmount
  discountType: 'percentage' | 'fixedAmount'
  message: string
}
```

Note `currentTier.discountAmount` is the raw config value — a percent, or **cents** for
`fixedAmount`.

A full example payload — the cart crossing from tier 1 into tier 2:

```js
// event.detail.resource on tier-change
{
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  widgetType: 'order-goal',
  discountId: 'discount-1478638797012',
  previousTier: {
    tierLevel: 1,
    minSpendCents: 5000,
    discountAmount: 10,
    discountType: 'percentage',
    message: 'Save 10%'
  },
  currentTier: {
    tierLevel: 2,
    minSpendCents: 10000,
    discountAmount: 15,        // percent — or CENTS when discountType is 'fixedAmount'
    discountType: 'percentage',
    message: 'Save 15%'
  },
  cartTotalCents: 11000
}
```

### Lifecycle

Each Order Goal instance also emits **mount** and **unmount** events as its behaviour
attaches and tears down — handy for wiring up (and cleaning up) custom integrations per
instance. Both **bubble** and carry a `DklWidgetEventDetail` resource. Order goals are
order-level, so the payload is just `widgetType` and `widgetId` (no product/variant).

#### `discount-kit-live:widget:mount`

`CustomEvent`

Fired once the controller has attached its behaviour to the (already server-rendered)
element, after the baseline tier is established. `resource`: `{ widgetType, widgetId }`.

#### `discount-kit-live:widget:unmount`

`CustomEvent`

Fired when the instance tears down — e.g. the element is removed, or the theme editor
re-renders the section. Same `resource` shape. Use it to detach any listeners or observers
you set up on mount.

```js
// event.detail.resource on widget:mount / widget:unmount
{
  widgetType: 'order-goal',
  widgetId: 'a1b2c3d4'         // the app block's id (null on a web component)
}
```

## Next steps

---

# Order Goal

Source: https://discountkit.app/docs/components/order-goal/overview/

![Image highlighting the DKL Order Goal component - layout: stacked](/images/components/dkl-order-goal-stacked-component.jpg)
    *DKL Order Goal component - layout: stacked*
    ![Image highlighting the DKL Order Goal component - layout: horizontal](/images/components/dkl-order-goal-horizontal-component.jpg)
    *DKL Order Goal component - layout: horizontal*

`<dkl-order-goal>` shows progress toward an **order-goal** discount's spend tiers from the
cart's items subtotal: a progress track, evenly-spaced tier markers, and a "Spend
**[amount]** more to save **[discount]**" message that flips to a success heading once every
tier is met.

It's a **light-DOM** component (like the [discount badge](/docs/components/discount-badge/overview/)) — no
shadow DOM and no CSS parts. The Liquid snippet server-renders the full UI so it paints server-side, and the component re-renders **in place** on cart updates — recomputing the
progress fraction, marker states, and message locally, which keeps it theme-agnostic.

:::note[Cart total]
The component drives off the theme's standard `shopify:cart:lines-update`
event, summing the cart's line costs into an items subtotal. When that yields no cart, it
falls back to reading `/cart.js`, so custom-cart configurations are respected. Tier
min-spends are compared against the presentment-currency subtotal with **no currency
conversion** — multi-currency stores get face-value comparisons.
:::

## On this component

:::note
Both placements need the **Discount Kit Live** app embed enabled, and render identically —
the same defaults back both. See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/)
for how to choose.
:::

## Accessibility

- **Progress bar semantics.** The track carries `role="progressbar"` with `aria-valuemin`,
  `aria-valuemax`, `aria-valuenow`, and a money-formatted `aria-valuetext` (e.g. "$40.00 of
  $100.00"), so assistive tech reports real progress toward the goal rather than a bare
  percentage.
- **Live progress message.** The "Spend [amount] more…" headline (and the success message)
  is an `aria-live="polite"` region, so it's announced as the cart total changes.
- **State beyond colour.** Met tiers are marked with both an `--active` class and a check
  icon, not colour alone. Keep `--dkl-og-progress-color` and the marker colours at sufficient
  contrast when restyling.

---

# Styling & Data Attributes

Source: https://discountkit.app/docs/components/order-goal/styling-and-data/

This is the shared reference for `<dkl-order-goal>` — the `data-*` attributes that drive its
behaviour, the `--dkl-og-*` tokens that style it, and the Light-DOM classes you can target.
The [app block](/docs/components/order-goal/app-block/) settings map onto these; on a [custom
element](/docs/components/order-goal/web-component/) you set them directly.

:::note[Using this reference with the app block]
When you place the [**DK: Order Goal** app block](/docs/components/order-goal/app-block/), it renders
its own `<dkl-order-goal>` and writes these values for you — so what applies depends on the
kind of override:

**Data attributes — No:**
The block sets every `data-*` itself, from its App block settings and the resolved discount.
Adding `data-*` to your own markup has no effect on a block instance; they're the configuration
surface for the [web component](/docs/components/order-goal/web-component/) only. To change block
behaviour, use its [settings](/docs/components/order-goal/app-block/).

**CSS styling tokens — Yes:**
They're CSS custom properties that inherit through the light DOM, so they style a block exactly
like a web component. The block's colour / radius / spacing pickers just write the matching
tokens into a scoped `<style>` rule for you. Any token **not** exposed as a setting (e.g.
`--dkl-og-marker-size`, `--dkl-og-marker-border-color`) you can still set yourself from your own CSS —
`:root`, the embed's **Custom CSS** field, or a rule targeting the block.

**CSS parts — N/A:**
This component is **light DOM**, so there are **no CSS parts**. Target the
[Light-DOM classes](#light-dom-classes) below instead — they work the same on a block or a
web component.
:::

:::tip[Token precedence]
A token the block writes from a chosen setting is scoped to the block's
id (`#dkl-og-{block.id}`), which is more specific than a `:root` rule — so to override *that*
token, either change the editor setting or match the specificity (target the block element).
Tokens the block leaves unset fall back to your CSS or the built-in default as normal.
:::

## Data attributes

All optional — on a web component the carrier supplies them by default. Set one to override.

#### `data-discount-id`

`metaobject handle` · default: `first eligible`

Pick a specific order-goal discount's carrier. The `discount-` prefix is optional; place one
tag per discount to show several.

#### `data-cart-total-cents`

`int` · default: `carrier (render-time subtotal)`

The baseline cart total.

#### `data-money-format`

`string` · default: `carrier (shop.money_format)`

Money format for JS-rendered amounts.

#### `data-message-template`

`string` · default: `Spend [amount] more to save [discount] on your order!`

The spend-more message. `[amount]` and `[discount]` are replaced at runtime.

#### `data-success-heading`

`string` · default: `Winner Winner 🎉`

Heading shown once every tier is met.

#### `data-success-message`

`string` · default: `You've unlocked all available savings`

Content shown once every tier is met.

#### `data-tier-save-label`

`string` · default: `Save [discount]`

Per-tier label; `[discount]` is the placeholder.

#### `data-tier-spend-label`

`string` · default: `when you spend [amount]+`

Per-tier spend line; `[amount]` is the placeholder.

#### `data-layout`

`"horizontal" | "stacked"` · default: `horizontal`

Layout variant. `stacked` arranges markers in a column with the progress bar rotated.

## CSS styling tokens

    ![Image highlighting the CSS styling tokens for the DKL Order Goal component - layout: stacked](/images/components/dkl-order-goal-stacked-css-tokens.jpg)
    *CSS styling tokens for the DKL Order Goal component - layout: stacked*
    ![Image highlighting the CSS styling tokens for the DKL Order Goal component - layout: horizontal](/images/components/dkl-order-goal-horizontal-css-tokens.jpg)
    *CSS styling tokens for the DKL Order Goal component - layout: horizontal*

`<dkl-order-goal>` is styled by a stylesheet loaded site-wide by the embed. Set any token
above the element (`:root`, the embed's Custom CSS, an inline `style`, or the block's scoped
rule).

#### `--dkl-og-margin-top`

default: `0`

Space above the widget (block **Margin top**).

#### `--dkl-og-margin-bottom`

default: `0`

Space below the widget (block **Margin bottom**).

#### `--dkl-og-background`

default: `var(--dkl-color-background-soft)`

Card background (block **Background color**).

#### `--dkl-og-padding`

default: `1rem`

Card padding (block **Padding**).

#### `--dkl-og-radius`

default: `var(--dkl-radius)`

Card corners (block **Border radius**).

#### `--dkl-og-font-size`

default: `inherit`

Base font size — emitted only when block **Font sizing** is *Custom*, else inherits the theme.

#### `--dkl-og-font-size-mobile`

default: `var(--dkl-og-font-size)`

Base font size at ≤749px (block **Font size (mobile)**, Custom only).

#### `--dkl-og-text-color`

default: `var(--dkl-color-text)`

Card text colour (block **Text color**).

#### `--dkl-og-tier-label-color`

default: `inherit`

The "Save [discount]" tier label (block **Tier label color**).

#### `--dkl-og-tier-spend-color`

default: `inherit`

The "when you spend [amount]+" tier line (block **Tier spend label color**).

#### `--dkl-og-track-color`

default: `var(--dkl-color-border)`

Progress track (unfilled bar) colour (block **Track color**).

#### `--dkl-og-progress-color`

default: `var(--dkl-color-accent)`

Progress fill colour (block **Progress bar color**).

#### `--dkl-og-marker-size`

default: `2rem`

Tier marker size.

#### `--dkl-og-marker-border-color`

default: `var(--dkl-color-border)`

Inactive marker border colour.

#### `--dkl-og-marker-bg`

default: `var(--dkl-color-background)`

Inactive marker fill (block **Icon background (not met)**).

#### `--dkl-og-marker-active-color`

default: `var(--dkl-color-accent)`

Active (met) marker fill (block **Icon background (met)**).

#### `--dkl-og-marker-icon-active-color`

default: `#ffffff`

Active marker check-icon colour.

:::note
The marker glyph is set via the `--dkl-og-icon` mask — the [app block](/docs/components/order-goal/app-block/)
swaps it for you through its icon image settings; on a web component you set the mask yourself.
:::

:::caution
Two further properties are runtime-internal, not theming knobs: `--dkl-og-progress` (the 0–1
fill fraction the component sets on the track) and `--dkl-og-icon` (the marker's mask). Don't
author them.
:::

## Light-DOM classes

`<dkl-order-goal>` is all light DOM — **no parts**. Target these classes directly.

#### `dkl-order-goal`

`host`

The card (host element).

#### `.dkl-order-goal__message`

`class`

The headline / progress message.

#### `.dkl-order-goal__progress`

`class`

The progress bar (with `.dkl-order-goal__progress-track`; the fill is the track's `::before`).

#### `.dkl-order-goal__tiers`

`class`

The tier row/column.

#### `.dkl-order-goal__tier`

`class`

The wrapper for each tier.

#### `.dkl-order-goal__tier-marker`

`class`

The marker dot (met: `.dkl-order-goal__tier-marker--active`; the icon glyph is its `::before`).

#### `.dkl-order-goal__tier-label`

`class`

The wrapper for the tier label.

#### `.dkl-order-goal__tier-text`

`class`

The "Save [discount]" text in the tier label.

#### `.dkl-order-goal__tier-amount`

`class`

The "when you spend [amount]+" text in the tier label.

## Examples

```css title="Restyle the progress fill and markers"
:root {
  --dkl-og-progress-color: #6d28d9;
  --dkl-og-marker-active-color: #6d28d9;
  --dkl-og-track-color: #ede9fe;
}

.dkl-order-goal__tier-marker--active {
  box-shadow: 0 0 0 3px #ede9fe;
}
```

```html title="Custom messaging"
<dkl-order-goal
  data-message-template="Add [amount] more for [discount] off!"
  data-success-heading="You did it! 🎉"
  data-success-message="Every reward unlocked"
  data-tier-save-label="[discount] off"
  data-tier-spend-label="at [amount]+"
></dkl-order-goal>
```

## Next steps

---

# Web Component

Source: https://discountkit.app/docs/components/order-goal/web-component/

A web component is the `<dkl-order-goal>` tag written directly into your theme's Liquid.
Order goals are order-level, so they live in the shop feed. On a product page the embed
pre-renders carriers for them, so the empty tag clones the default and renders server-side:

```html
<dkl-order-goal></dkl-order-goal>
```

To target a specific order-goal discount (rather than the first eligible one), set
`data-discount-id` — that goal's carrier must also be present on the page. The `discount-`
prefix is optional, and you can place one `<dkl-order-goal>` tag per discount to show several:

```html
<dkl-order-goal data-discount-id="1478638797012"></dkl-order-goal>
```

## Reacting to changes

`<dkl-order-goal>` emits `discount-kit-live:order-goal:tier-change` when the cart total
crosses a tier boundary (the initial render establishes the baseline silently). To run your
own code on a tier change, listen for that event — see its [Events](/docs/components/order-goal/events/)
page and [Listen for tier changes](#examples) in the examples below.

## Examples

For the full list of `data-*` attributes you can set, see
[Styling & Data Attributes](/docs/components/order-goal/styling-and-data/).

```html title="Override attributes + tokens"
<dkl-order-goal
  data-layout="stacked"
  data-message-template="Add [amount] more for [discount] off!"
  data-success-heading="You did it! 🎉"
  style="
    --dkl-og-progress-color: #6d28d9;
    --dkl-og-marker-active-color: #6d28d9;
    --dkl-og-background: #f5f3ff;
    --dkl-og-radius: 16px;
  "
></dkl-order-goal>
```

```html title="Stacked layout"
<dkl-order-goal data-layout="stacked"></dkl-order-goal>
```

```js title="Listen for tier changes"
// Fires whenever the cart total crosses a tier boundary
document.addEventListener(
  'discount-kit-live:order-goal:tier-change',
  (event) => {
    const { currentTier, previousTier, cartTotalCents, discountId } =
      event.detail.resource

    // currentTier is null below the first tier
    if (currentTier && (!previousTier || currentTier.tierLevel > previousTier.tierLevel)) {
      console.log(`Unlocked tier ${currentTier.tierLevel} on ${discountId}!`)
    }
  }
)
```

```js title="Example event payload"
// event.detail.resource on tier-change — here the cart crossed from tier 1 into tier 2
{
  widgetId: null,
  widgetType: 'order-goal',
  discountId: 'discount-1478638797012',
  previousTier: {
    tierLevel: 1,
    minSpendCents: 5000,
    discountAmount: 10,
    discountType: 'percentage',
    message: 'Save 10%'
  },
  currentTier: {
    tierLevel: 2,
    minSpendCents: 10000,
    discountAmount: 15,        // percent — or CENTS when discountType is 'fixedAmount'
    discountType: 'percentage',
    message: 'Save 15%'
  },
  cartTotalCents: 11000
}
```

## Next steps

---

# Overview

Source: https://discountkit.app/docs/components/overview/

Live Components are a set of `<dkl-*>` web components that render discount UI
directly in your storefront — a [volume picker](/docs/components/volume-picker/overview/), a
[discount-aware price](/docs/components/price/overview/), a [max-discount badge](/docs/components/discount-badge/overview/),
and an [order-goal progress bar](/docs/components/order-goal/overview/). They read the same
[Discount Kit Live data](/docs/live/introduction/) you already sync to your storefront, are
**server-rendered** so they paint with **no flicker**, and theme entirely through
`--dkl-*` CSS styling tokens.

:::note
These components require the discounts they display to be tagged `dk:live` and synced
to your storefront. See the [Live introduction](/docs/live/introduction/) for how syncing works.
:::

## Enable the 'Discount Kit Live' app embed

Every component depends on the **Discount Kit Live** app embed. Enable it once, per
theme:

1. **Open the theme editor**

   In the Shopify admin, go to **Online Store → Themes** and click **Customize**.

2. **Find the app embeds**

   Open **App embeds** in the left sidebar.

3. **Enable Discount Kit Live**

   Toggle **Discount Kit Live** on, then click **Save**.

The embed loads the shared runtime (styles + behaviour) site-wide and pre-renders the
data each component needs. Without it enabled, the components have nothing to render
from.

:::note
The embed also exposes a **Debug mode** toggle and a **Custom CSS** field. Debug mode
logs both the standard storefront events and every Discount Kit Live component event
(mount/unmount, tier-change, price-change) to the browser console; Custom CSS is a
convenient place to set global `--dkl-*` [styling tokens](/docs/components/global-styling/).
:::

## Two ways to place a component

Each component can be added either as a **theme app block** (configured in the theme
editor) or as a **web component** (dropped straight into theme markup). They render
identically — the same defaults back both paths.

    Add **DK: Price**, **DK: Volume Groups**, etc. through the theme editor. Every
    setting (colours, spacing, labels) is exposed in the editor — no code. This is the
    right choice for most merchants, and the only way to render in **product cards** on
    collection pages.
    Drop the element directly into your theme's Liquid — e.g. `<dkl-price></dkl-price>`.
    On a product page it needs **zero attributes**: it renders from a pre-staged carrier
    with no flicker. For developers customizing themes directly.

See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/) for a full
comparison and how to choose.

## Prerequisites

Beyond enabling the **Discount Kit Live** app embed and tagging your discounts `dk:live`, the
Live Components need one thing from your **theme**: support for Shopify's
[**Standard Storefront Events**](https://shopify.dev/docs/storefronts/themes/best-practices/standard-events).

The components react to shopper actions — selecting a variant, changing the cart — by listening
for these events, so your theme must **publish** them for the components to update in response:

- **`shopify:product:select`** drives variant-aware updates:
  - the [price](/docs/components/price/overview/) re-prices on a variant change
  - the [volume picker](/docs/components/volume-picker/overview/) re-calculates the selected tier on variant change
  - the [badge](/docs/components/discount-badge/overview/) re-picks the best discount
- **`shopify:cart:lines-update`** drives cart-level updates:
  - the [order goal](/docs/components/order-goal/overview/)'s progress updates as the cart changes.

This new way of tracking standard storefront events ensures that the components work consistently across all themes, once the new events are fully adopted by developers, rather than relying on theme specific event systems.

Shopify's Horizon v4.0.0+ comes with built in support for these. For older themes, follow Shopify's [Standard Storefront Events](https://shopify.dev/docs/storefronts/themes/best-practices/standard-events)
guide to integrate the events into your theme.

[Shopify's Standard Actions](https://shopify.dev/docs/storefronts/themes/best-practices/standard-actions) are globally distributed across all Shopify storefronts already, so you don't need to worry about integrating them into your theme unless you need to define custom actions.

:::note
The components still **render** without the standard events — they're server-rendered from their
carrier or app block, so they paint with no flicker regardless. They just won't **react** to
variant or cart changes until your theme publishes the events.
:::

## Theming

All component styling is driven by `--dkl-*` CSS styling tokens — global brand tokens shared
by every component, plus per-component tokens for fine control. See
[Styling](/docs/components/global-styling/) for the full token reference, how to apply them, and how
to target structural elements.

## The components

---

# App block

Source: https://discountkit.app/docs/components/price/app-block/

The **DK: Price** app block renders `<dkl-price>` with no code — you add it in the theme
editor and configure every option through its settings panel. It's available on **product
templates**.

## Add the block

1. **Open the theme editor**

   In the Shopify admin, go to **Online Store → Themes** and click **Customize**. Make sure the **Discount Kit Live**
   app embed is enabled.

2. **Edit a product template**

   Switch the top template selector to a **Product** template.

3. **Add the DK: Price block**

   In the section where you want the price, click **Add block** and choose **DK: Price**, then position it where the
   price should appear.

4. **Hide the theme's native price**

   To avoid showing two prices, hide your theme's built-in price element where you've placed **DK: Price**.

:::tip[Pairing with the volume picker]
Leave the [volume picker's](/docs/components/volume-picker/overview/) price element selector blank so it connects to the `<dkl-price>` element by default, and let **DK: Price** be the single element that updates the displayed price.
:::

## Settings

Every setting maps to a `data-*` attribute or `--dkl-*` token under the hood — see
[Styling & Data Attributes](/docs/components/price/styling-and-data/) for the equivalents.

### Savings badge

#### `Show savings badge`

`checkbox` · default: `off`

Shows how much is saved vs the original price (on sale, or when a volume tier is selected). The settings below appear
once this is on.

#### `Savings format`

`select` · default: `Percentage`

How the saving displays — **Percentage** (e.g. 20%) or **Amount** (e.g. $5.00).

#### `Savings label`

`text` · default: `Save`

The savings badge's leading label, e.g. "**Save** 15%".

#### `Extra discount label`

`text` · default: `+ an extra`

Shown between the sale and tier savings, e.g. "Save 10% **+ an extra** 15%".

#### `Savings badge background color`

`color` · default: `var(--dkl-color-success)`

Background colour for the savings badge.

#### `Savings badge text color`

`color` · default: `#ffffff`

Text colour within the savings badge.

#### `Savings badge corner radius`

`range` · default: `8px`

Corner radius for the savings badge, 0–24px.

### Spacing

#### `Margin top`

`range` · default: `0px`

Space above the widget, 0–80px.

#### `Margin bottom`

`range` · default: `0px`

Space below the widget, 0–80px.

### Colors

#### `Price color`

`color` · default: `inherit`

The main price. Defaults to the theme's inherited text colour.

#### `Discounted price color`

`color` · default: `var(--dkl-price-color)`

Shown when a volume tier is selected. Falls back to the **Price color**.

#### `Compare price color`

`color` · default: `inherit`

The compared-to (struck-through) price.

:::note
Colour and radius pickers are written into a scoped `<style>` rule the block emits, so they
live-update in the theme editor and stay overridable by your own CSS. Unset colour pickers
are skipped, so text never goes invisible.
:::

## Next steps

---

# Events

Source: https://discountkit.app/docs/components/price/events/

`<dkl-price>` is event-driven. It has **no direct reference** to the
[volume picker](/docs/components/volume-picker/overview/) — instead it listens for the picker's tier-change
event and the theme's variant-change events, and updates the price accordingly.

## Listens for

#### `discount-kit-live:volume-discount:tier-change`

`CustomEvent`

Emitted by the [volume picker](/docs/components/volume-picker/overview/). Matched by product id — a
selected tier shows the discounted price, a `null` tier reverts to base. Coupling is by
event name and product id only, with no import between the two components.

Honours the event's `updatesPrice` flag: if the picker's **"Update price when a tier is
selected"** setting is off, `<dkl-price>` **ignores the tier for pricing** (the event still
fires for other listeners).

It also reacts to the host theme's **variant-change** events: on a variant change it updates
the base price and re-applies the active tier, recomputing the discount off the new variant's
price (sale-priced variants included).

## Emits

`<dkl-price>` emits a **price-change** event whenever its displayed price updates, plus
**mount / unmount** lifecycle events. All bubble, so you can listen on `document`.

:::note[`widgetId` and `variantId`]
`widgetId` is the **app block's id** — it's `null` on a web component,
`variantId` is the **current** variant and
updates as the shopper switches variants (not just the variant at page load).
:::

### Price change

#### `discount-kit-live:price:change`

`CustomEvent`

Fired whenever the displayed price changes — when a volume tier is selected or deselected, or
the variant changes. **Not** fired on initial mount (the server-rendered price is already in
the DOM), and **deduped** — a recompute that lands on the same price (e.g. switching to an
equally-priced variant) doesn't fire. The detail carries `resource` with the previous and new
price, mirroring the tier event's `previousTier` / `currentTier`:

```ts
resource: {
  widgetType: 'price'
  widgetId: string | null
  productId: number | null
  variantId: number | null
  previousPrice: PriceState | null   // null on the first change after mount
  currentPrice:  PriceState
}

type PriceState = {
  priceCents: number              // displayed price (discounted when a tier is active)
  compareAtCents: number | null   // the struck-through "before" price, or null
  discounted: boolean             // whether a volume tier is applied
  tier: VolumeDiscountTier | null // the active tier, or null
}
// VolumeDiscountTier: { index, quantity, discountAmount, discountType, unitPriceCents }
```

A full example payload — selecting a tier that moves the price from £20.00 to £18.00:

```js
// event.detail.resource on price:change
{
  widgetType: 'price',
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  productId: 7820000000001,
  variantId: 41200000000001,   // the current variant — updates on a variant change
  previousPrice: {
    priceCents: 2000,
    compareAtCents: null,
    discounted: false,
    tier: null
  },
  currentPrice: {
    priceCents: 1800,
    compareAtCents: 2000,      // the original price, now struck through
    discounted: true,
    tier: {
      index: 1,
      quantity: 3,
      discountAmount: 10,
      discountType: 'percentage',
      unitPriceCents: 1800
    }
  }
}
```

### Lifecycle

The mount / unmount events fire as the instance's behaviour attaches and tears down — handy
for wiring up (and cleaning up) custom integrations per instance. Both carry a
`DklWidgetEventDetail` resource.

#### `discount-kit-live:widget:mount`

`CustomEvent`

Fired once the controller has attached its behaviour to the (already server-rendered)
element. `resource`: `{ widgetType, widgetId, productId?, variantId? }` — `productId` and
`variantId` are included when known.

#### `discount-kit-live:widget:unmount`

`CustomEvent`

Fired when the instance tears down — e.g. the element is removed, or the theme editor
re-renders the section. Same `resource` shape. Use it to detach any listeners or observers
you set up on mount.

```js
// event.detail.resource on widget:mount / widget:unmount
{
  widgetType: 'price',
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  productId: 7820000000001,
  variantId: 41200000000001
}
```

## Next steps

---

# Discount Price

Source: https://discountkit.app/docs/components/price/overview/

![DKL Price component](/images/components/dkl-price-component.jpg)

*DKL Price component*

`<dkl-price>` renders a product's price in its own shadow DOM rather than hijacking the
theme's price element — so it fully controls the markup and styling. It's
**event-driven**: it has no direct reference to the [volume picker](/docs/components/volume-picker/overview/),
but reacts to the tier-change events the picker emits.

- When a [volume tier](/docs/components/volume-picker/overview/) is selected (matched by product id), it
  shows the **discounted price** as the main amount and the **original price struck
  through** — the compare-at when the variant is on sale, otherwise the regular price.
  Deselecting reverts to the base price.
- On a **variant change** it updates the base price and re-applies the active tier,
  recomputing the discount off the new variant's price (sale-priced variants included).

While a tier is active the component sets `data-dkl-discounted` on itself, so CSS can
colour the discounted price distinctly. An optional **savings badge** shows how much the
shopper saves.

## On this component

:::note
Both placements need the **Discount Kit Live** app embed enabled, and render identically —
the same defaults back both. See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/)
for how to choose.
:::

## Accessibility

- **Labelled amounts.** Each amount is preceded by a visually-hidden label (`::part(vh)`) —
  "Price" for the main amount, "Regular price" for the struck-through compare-at — so screen
  readers can tell the live price from the original. Don't remove or repurpose `::part(vh)`.
- **Live price announcements.** When a variant or tier changes, the new price is announced
  through a managed `aria-live="polite"` region — concise, e.g. "£18.00, was £24.00, Save
  25%". It fires only on a change, never on initial load, and lives on a dedicated region
  rather than the host (a live region wrapping shadow DOM is monitored unreliably across
  screen readers).
- **Contrast.** When restyling the savings badge, keep `--dkl-price-savings-color` and
  `--dkl-price-savings-background` at sufficient contrast.

---

# Styling & Data Attributes

Source: https://discountkit.app/docs/components/price/styling-and-data/

This is the shared reference for `<dkl-price>` — the `data-*` attributes that drive its
behaviour, the `--dkl-*` tokens that style it, and the CSS parts you can target. The [app
block](/docs/components/price/app-block/) settings map onto these; on a [web component](/docs/components/price/web-component/) you set them directly.

:::note[Using this reference with the app block]
When you place the [**DK: Price** app block](/docs/components/price/app-block/), it renders its own
`<dkl-price>` and writes these values for you — so what applies depends on the kind of override:

**Data attributes - No:**
The block sets every `data-*` itself, from its App block settings and the resolved discount. Adding `data-*` to your own markup has no effect on a block instance; they're the configuration surface for the [web component](/docs/components/price/web-component/) only. To change block behaviour, use its [settings](/docs/components/price/app-block/).

**CSS styling tokens — Yes:**
They're CSS custom properties that inherit
through the shadow boundary, so they style a block exactly like a web component. The block's
colour / radius / spacing pickers just write the matching tokens into a scoped `<style>` rule
for you. Any token **not** exposed as a setting (e.g. `--dkl-price-gap`, `--dkl-price-font-size`)
you can still set yourself from your own CSS — `:root`, the embed's **Custom CSS** field, or a
rule targeting the block.

**CSS parts — Yes:**
The shadow DOM is identical, so `::part()` works the same on a
block or a web component.
:::

:::tip[Token precedence]
A token the block writes from a chosen setting is scoped to the block's id (`#dkl-price-{block.id}`),
which is more specific than a `:root` rule — so to override *that* token, either change the editor
setting or match the specificity (target the block element). Tokens the block leaves unset fall back to your CSS or
the built-in default as normal.
:::

## Data attributes

All optional — on a web component the carrier supplies them by default. Set one to override.

#### `data-base-price-cents`

`int (cents)` · default: `carrier (the variant's price)`

The regular price — the component's base amount.

#### `data-compare-at-cents`

`int (cents)` · default: `carrier (set only when on sale)`

The native sale compare-at price. Struck through when no tier is active.

#### `data-money-format`

`string` · default: `carrier (shop.money_format)`

Money format string. Falls back to `Shopify.formatMoney`, then `Intl`.

#### `data-show-savings`

`"true" | "false"` · default: `false`

Show the savings badge (saving versus the original / highest price).

#### `data-savings-format`

`"percentage" | "amount"` · default: `percentage`

How the savings badge displays the saving.

#### `data-savings-label`

`string` · default: `Save`

The badge's leading label, e.g. "**Save** 15%".

#### `data-savings-extra-label`

`string` · default: `+ an extra`

Connector between the sale saving and the tier saving, e.g. "Save 10% **+ an extra** 15%".

#### `data-dkl-discounted`

`presence` · default: `unset`

**Set by the component** while a tier is active — a styling hook only. Don't author it yourself.

## CSS styling tokens

![Descriptive alt text](/images/components/dkl-price-css-tokens.jpeg)

*CSS styling tokens for the DKL Price component*

`<dkl-price>` has no shadow `<style>` — its stylesheet (loaded site-wide by the embed) is
the single source, styling the host and parts. Set any token above the element (`:root`,
the embed's Custom CSS, an inline `style`, or the block's scoped rule).

#### `--dkl-price-gap`

default: `0.4rem`

Gap between price and compare-at.

#### `--dkl-price-font-size`

default: `inherit`

Font size for all price entities (main price, compare-at, savings badge)

#### `--dkl-price-font-weight`

default: `600`

Main price font weight

#### `--dkl-price-color`

default: `inherit`

Main price color

#### `--dkl-price-sale-color`

default: `var(--dkl-price-color)`

Main price while a tier is active (`[data-dkl-discounted]`).

#### `--dkl-price-compare-opacity`

default: `0.6`

Struck-through compare-at opacity

#### `--dkl-price-compare-font-weight`

default: `400`

Compare-at font weight

#### `--dkl-price-compare-color`

default: `inherit`

Compare-at color

#### `--dkl-price-compare-decoration`

default: `line-through`

Compare-at text decoration

#### `--dkl-price-savings-font-size`

default: `0.8em`

Savings badge font size

#### `--dkl-price-savings-font-weight`

default: `600`

Savings badge font weight

#### `--dkl-price-savings-color`

default: `#ffffff`

Savings badge text color

#### `--dkl-price-savings-background`

default: `var(--dkl-color-success)`

Savings badge background color

#### `--dkl-price-savings-radius`

default: `var(--dkl-radius)`

Savings badge corner radius

#### `--dkl-price-savings-padding`

default: `0.125rem 0.5rem`

Savings badge padding (vertical and horizontal)

Also reads the global brand tokens `--dkl-font-family` and `--dkl-color-text`.

## CSS parts

![Image highlighting the CSS parts for the DKL Price component](/images/components/dkl-price-css-parts.jpg)

*CSS parts for the DKL Price component*

`<dkl-price>` is fully shadow DOM. Target its internals with `::part()`.

#### `price`

`CSSPart`

The main price (the discounted price while a tier is active).

#### `compare-at`

`CSSPart`

The struck-through compare-at wrapper.

#### `compare-at-amount`

`CSSPart`

The compare-at number.

#### `savings`

`CSSPart`

The savings line wrapper.

#### `savings-label`

`CSSPart`

The savings label text.

#### `savings-amount`

`CSSPart`

The savings amount.

## Examples

```css title="Style via :root tokens"
:root {
  --dkl-price-sale-color: #c0392b;
  --dkl-price-compare-opacity: 1;
  --dkl-price-compare-color: #888;
}
```

```css title="Style via ::part()"
dkl-price::part(price) {
  font-size: 1.5rem;
  font-weight: 700;
}
```

```html title="Data attribute overrides for web component"
<dkl-price
  data-show-savings="true"
  data-savings-format="amount"
  data-savings-label="You save"
></dkl-price>
```

## Next steps

---

# Web Component

Source: https://discountkit.app/docs/components/price/web-component/

A web component is the `<dkl-price>` tag written directly into your theme's Liquid. On a
**product page** it needs **zero attributes** — it clones a pre-staged carrier and renders
the primary product's price server-side.

## Usage

On a product page, add the `<dkl-price>` web component — it renders the primary product's price server-side:

```html
<dkl-price></dkl-price>
```

:::tip[Pairing with the volume picker]
To let `<dkl-price>` own the price display, set the
volume picker's price target to `none` (`data-price-target="none"`) and hide the theme's
native price. The picker then only emits tier-change events, and `<dkl-price>` is the single
element that updates.
:::

:::caution[Beta Limitation for Web Components: Single Product Context]
During beta of the DKL Live Components, a web component is only recommended for product pages / where the products shown on the page are static on page load.

For use on a page where new product instances are loaded in via the Section Rendering API / Ajax (such as a paginated collection page for example) we recommend using the app block
instead. See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/).
:::

## Reacting to changes

`<dkl-price>` emits a `discount-kit-live:price:change` event whenever its displayed price
updates — the recommended hook for running your own code when the price moves. It carries the
previous and new price (see the [Events](/docs/components/price/events/#price-change) reference). See
[Listen for price changes](#examples) below.

Two narrower alternatives:

- **Listen for the tier event** — the volume picker's
  `discount-kit-live:volume-discount:tier-change`, e.g. to read the selected tier's quantity.
  See [Listen for tier changes](#examples).
- **Watch the discounted state** — if you only care about whether _this_ element is showing a
  discount, observe its `data-dkl-discounted` attribute (set while a tier is active) with a
  `MutationObserver`:

```js
// Handles any number of <dkl-price> elements on the page
document.querySelectorAll('dkl-price').forEach((price) => {
  new MutationObserver(() => {
    const discounted = price.hasAttribute('data-dkl-discounted')
    // e.g. flag the surrounding card while a discounted tier is selected
    price.closest('.product-card')?.classList.toggle('is-discounted', discounted)
  }).observe(price, { attributes: true, attributeFilter: ['data-dkl-discounted'] })
})
```

## Examples

For the full list of `data-*` attributes you can set, see
[Styling & Data Attributes](/docs/components/price/styling-and-data/).

```liquid title="Override attributes + tokens"
<dkl-price
  data-show-savings="true"
  data-savings-format="amount"
  data-savings-label="You save"
  style="
    --dkl-price-font-size: 1.4rem;
    --dkl-price-font-weight: 700;
    --dkl-price-sale-color: #c0392b;
    --dkl-price-compare-opacity: 1;
  "
></dkl-price>
```

```js title="Listen for price changes"
// The recommended hook: fires whenever the displayed price updates, with the
// previous and new price states.
document.addEventListener('discount-kit-live:price:change', (event) => {
  const { productId, previousPrice, currentPrice } = event.detail.resource

  const fmt = (cents) =>
    (cents / 100).toLocaleString(undefined, {
      style: 'currency',
      currency: window.Shopify?.currency?.active ?? 'USD',
    })

  console.log(
    `Product ${productId}: ` +
      `${previousPrice ? fmt(previousPrice.priceCents) : '—'} → ${fmt(currentPrice.priceCents)}` +
      (currentPrice.discounted ? ' (discounted)' : ''),
  )
})
```

```js title="Listen for tier changes"
// React to volume-tier selections to drive your own UI alongside the price —
// here, a custom "Buy N at X each" summary element somewhere on the page:
//   <p data-tier-summary="7820000000001" hidden></p>
const summary = document.querySelector('[data-tier-summary]')

const money = (major) =>
  major.toLocaleString(undefined, {
    style: 'currency',
    currency: window.Shopify?.currency?.active ?? 'USD',
  })

document.addEventListener('discount-kit-live:volume-discount:tier-change', (event) => {
  const { productId, currentTier } = event.detail.resource

  // Scope to the product this summary belongs to — handy when several pickers
  // / prices share a page (e.g. the main product plus recommendations).
  if (productId !== Number(summary.dataset.tierSummary)) return

  // currentTier is null when the shopper clears their selection.
  if (!currentTier) {
    summary.hidden = true
    return
  }

  // unitPriceCents is the per-item price; discountAmount is a percentage for
  // 'percentage' tiers, or a major-unit amount for 'fixedAmount' tiers.
  const { quantity, unitPriceCents, discountType, discountAmount } = currentTier
  const saving =
    discountType === 'percentage' ? `${discountAmount}% off` : `${money(discountAmount)} off each`

  summary.hidden = false
  summary.textContent = `Buy ${quantity}+ at ${money(unitPriceCents / 100)} each — ${saving}`
})
```

## Next steps

---

# Roadmap

Source: https://discountkit.app/docs/components/roadmap/

The Live Components are in **beta**, and we're actively expanding them. This is a
forward-looking view of what we're building and exploring — **not a commitment or a schedule**.
Priorities and scope may change.

:::note
Have a request, or a use case a component doesn't cover yet? Tell us at
[support@discountkit.app](mailto:support@discountkit.app) — it directly helps us prioritise.
:::

## In Progress

  We can't say much on this one yet, but we're working on it!

  A gift-selector component for GWP discounts — surfacing the free-gift tiers, the products a
  shopper can choose from, and how many gifts they've unlocked, the same drop-in way as the
  other widgets.

  `<dkl-price>` reacting to the selected **selling plan** and showing the plan-adjusted price,
  with a defined rule for how a subscription discount stacks with a selected volume tier.

  Surfacing unit price (`unit_price` / `unit_price_measurement`) alongside the main price, for
  stores that display per-unit pricing.

## Exploration

  Currently, v2 components are designed to output a single discount per instance. We are exploring the possibility of creating components that can output multiple discounts per instance but organised logically based on the iscount benefit for the customer. I.e If you have 2 different volume discounts created on a product, we'll merge these together in the components UI.

  Today a web component only renders where a server-rendered carrier exists — product
  pages. We're exploring a path to make web components work in **product cards, paginated
  collections, and Ajax / Section-Rendering-API-loaded content**, so a hand-placed `<dkl-*>` tag
  can resolve any product on the page. For these contexts today, use the
  [app block](/docs/components/app-blocks-vs-web-components/).

  Hardening the components toward a stable, general-availability release.

---

For what's already shipped, see the [Changelog](/changelog/).

---

# App block

Source: https://discountkit.app/docs/components/volume-picker/app-block/

The **DK: Volume Groups** app block renders `<dkl-volume-picker-radio-groups>` with no code —
you add it in the theme editor and configure every option through its settings panel. It's
available on **product templates**. The block resolves the eligible volume discount for you
and exposes the behaviour toggles (native-price update, quantity sync) and styling as
settings.

## Add the block

1. **Open the theme editor**

   In the Shopify admin, go to **Online Store → Themes** and click **Customize**. Make sure the **Discount Kit Live**
   app embed is enabled.

2. **Edit a product template**

   Switch the top template selector to a **Product** template.

3. **Add the DK: Volume Groups block**

   In the section where you want the tiers, click **Add block** and choose **DK: Volume Groups**, then position it
   where the picker should appear.

:::tip[Pairing with Discount Price]
To let [**DK: Price**](/docs/components/price/overview/) own the displayed price, set the price target to none — leave the
**Price element selector** blank so the picker connects to the `<dkl-price>` element by default, and let **DK: Price**
be the single element that updates the displayed price.
:::

## Settings

Every setting maps to a `data-*` attribute or `--dkl-*` token under the hood — see
[Styling & Data Attributes](/docs/components/volume-picker/styling-and-data/) for the equivalents.

### Discount & display

#### `Discount`

`metaobject`

Show only this volume discount. Leave empty to show the first eligible one.

#### `Style`

`select` · default: `Cards`

**Cards**, or **Mini buttons** (a compact grid; the per-tier price line is hidden).

#### `Title`

`text`

Optional heading above the tiers.

#### `Tier heading`

`text` · default: `Buy [tier_qty]+`

Use `[tier_qty]` for the tier quantity.

#### `Unit label`

`text` · default: `/ea`

#### `Discount label`

`text` · default: `off each item`

#### `Price unavailable label`

`text` · default: `No discount available`

### Behaviour

#### `Update price when a tier is selected`

`checkbox` · default: `true`

Whether selecting a tier updates the displayed price — both the theme's native price element
and the [`<dkl-price>`](/docs/components/price/overview/) component. When off, the tier-change event
still fires (so custom integrations keep working), but no price display reflects the tier.

#### `Price element selector`

`text` · default: `auto-detect`

Advanced: CSS selector for the theme's price element. Leave blank to auto-detect (or to pair with `<dkl-price>`).

#### `Sync with the quantity selector`

`checkbox` · default: `true`

Bi-directional sync of the theme's quantity selector to the selected tier's quantity

#### `Quantity input selector`

`text` · default: `auto-detect`

Advanced: CSS selector for the theme's quantity input. Leave blank to auto-detect.

#### `Quantity sync event`

`text`

Advanced: Optional event name to trigger quantity sync.

### Spacing & sizing

#### `Margin top`

`range` · default: `0px`

Space above the widget, 0–80px.

#### `Margin bottom`

`range` · default: `0px`

Space below the widget, 0–80px.

#### `Font sizing`

`select` · default: `Inherit (theme)`

**Inherit**, or **Custom** (reveals the sizes below).

#### `Font size (desktop)`

`range` · default: `15px`

10–32px. Custom only.

#### `Font size (mobile)`

`range` · default: `14px`

8–28px. Custom only.

#### `Border radius`

`range` · default: `8px`

Option corner radius, 0–24px.

### Colors

#### `Text color`

`color` · default: `#1a1a1a`

#### `Price color`

`color` · default: `#1a1a1a`

#### `Border color`

`color` · default: `#e5e5e5`

Resting card border.

#### `Selected tier background color`

`color` · default: `#ffffff`

#### `Selected tier text color`

`color` · default: `#1a1a1a`

#### `Selected tier price color`

`color` · default: `#1a1a1a`

#### `Selected tier border color`

`color` · default: `#000000`

Border and ring of the selected tier.

## Next steps

---

# Events

Source: https://discountkit.app/docs/components/volume-picker/events/

`<dkl-volume-picker-radio-groups>` is the source of the tier-change event in Discount Kit
Live. It has **no direct reference** to [`<dkl-price>`](/docs/components/price/overview/) — instead
it emits a tier-change event that the price (and any of your own code) can listen for,
coupled by event name and product id only.

## Emits

:::note[`widgetId` and `variantId`]
`widgetId` is the **app block's id** — it's `null` on a web component
which has no block. `variantId` is the product variant the picker is
bound to.
:::

#### `discount-kit-live:volume-discount:tier-change`

`CustomEvent`

Fired when a tier is selected or deselected. **Bubbles**, so you can listen on `document`.
The detail carries `resource`:

```ts
{
  productId, variantId, widgetId, widgetType,
  previousTier: VolumeDiscountTier | null,
  currentTier:  VolumeDiscountTier | null,  // null = deselected
  updatesPrice: boolean                     // see below
}
// VolumeDiscountTier: { index, quantity, discountAmount, discountType, unitPriceCents }
```

:::note[`updatesPrice`]
Reflects the picker's **"Update price when a tier is selected"** setting
(`data-update-price-on-change`). When it's `false`, price components like
[`<dkl-price>`](/docs/components/price/overview/) **ignore the tier for pricing** — but the event
still fires, so your own integrations keep receiving it.

[`<dkl-price>`](/docs/components/price/overview/) listens for this when `updatesPrice` is `true`, matched by product id — a
selected tier shows the discounted price, a `null` tier reverts to base.
:::

A full example payload:

```js
// event.detail.resource on tier-change
{
  productId: 7820000000001,
  variantId: 41200000000001,
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  widgetType: 'volume-picker-radio-groups',
  previousTier: null,
  currentTier: {
    index: 1,
    quantity: 3,
    discountAmount: 10,      // percent for 'percentage', major-unit amount for 'fixedAmount'
    discountType: 'percentage',
    unitPriceCents: 1800     // the per-item discounted price
  },
  updatesPrice: true         // false → <dkl-price> ignores the tier for pricing
}
```

### Lifecycle

Each Volume Picker instance also emits **mount** and **unmount** events as its behaviour
attaches and tears down — handy for wiring up (and cleaning up) custom integrations per
instance. Both **bubble** and carry the same `DklWidgetEventDetail` resource.

#### `discount-kit-live:widget:mount`

`CustomEvent`

Fired once the controller has attached its behaviour to the (already server-rendered)
element. `resource`: `{ widgetType, widgetId, productId?, variantId? }` — `productId` and
`variantId` are included when known.

#### `discount-kit-live:widget:unmount`

`CustomEvent`

Fired when the instance tears down — e.g. the element is removed, or the theme editor
re-renders the section. Same `resource` shape. Use it to detach any listeners or observers
you set up on mount.

```js
// event.detail.resource on widget:mount / widget:unmount
{
  widgetType: 'volume-picker-radio-groups',
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  productId: 7820000000001,
  variantId: 41200000000001
}
```

## Next steps

---

# Volume Picker

Source: https://discountkit.app/docs/components/volume-picker/overview/

![Image highlighting the DKL Volume Picker component](/images/components/dkl-volume-cards-component.jpg)
    *DKL Volume Picker component - layout: cards*
    ![Image highlighting the DKL Volume Picker component - layout: mini-buttons](/images/components/dkl-volume-mini-component.jpg)
    *DKL Volume Picker component - layout: mini-buttons*

`<dkl-volume-picker-radio-groups>` is a product-page selector for volume discounts. Each
tier ("Buy 3+", "Buy 5+"…) is a radio card. The radio inputs live in **light DOM** so they
join the product form, and project into the component's shadow DOM through a `<slot>`; the
shadow holds the title and layout.

Selecting a tier:

- emits `discount-kit-live:volume-discount:tier-change`, consumed by
  [`<dkl-price>`](/docs/components/price/overview/);
- optionally updates the theme's **native price** element (when enabled), drawing the
  discounted unit price with a synthetic strikethrough;
- optionally syncs the theme's **quantity selector** to the tier's quantity.

Tiers (quantity, discount type/amount, pre-computed unit price) are server-rendered onto
each radio as `data-dkl-*` attributes, which the component reads.

## On this component

:::note
Both placements need the **Discount Kit Live** app embed enabled, and render identically —
the same defaults back both. See [App blocks vs. Web Components](/docs/components/app-blocks-vs-web-components/)
for how to choose.
:::

## Accessibility

- **Native form semantics.** Each tier is a real `<input type="radio">` wrapped in a
  `<label>`, grouped in a `role="radiogroup"` inside a `<fieldset>`/`<legend>`. So keyboard
  users get native arrow-key navigation between tiers, the whole card is a click target, and
  the selection participates in the product form.
- **Labelled group.** The radiogroup is labelled by the title (`aria-labelledby`), falling
  back to an `aria-label` of "Volume discount options" when no title is shown.
- **Unavailable tiers are disabled.** On a sold-out or excluded variant the tier inputs
  render `disabled`, so they're skipped in the tab/arrow order rather than offering a
  dead-end selection.
- **Selection announcements.** Selecting or clearing a tier is announced through a managed
  `aria-live` region ("… selected" / "Volume discount removed").

---

# Styling & Data Attributes

Source: https://discountkit.app/docs/components/volume-picker/styling-and-data/

This is the shared reference for `<dkl-volume-picker-radio-groups>` — the `data-*` attributes
that drive its behaviour, the `--dkl-*` tokens that style it, and the CSS parts and light-DOM
classes you can target. The [app block](/docs/components/volume-picker/app-block/) settings map onto
these; on a [web component](/docs/components/volume-picker/web-component/) you set them directly.

:::note[Using this reference with the app block]
When you place the [**DK: Volume Groups** app block](/docs/components/volume-picker/app-block/), it
renders its own `<dkl-volume-picker-radio-groups>` and writes these values for you — so what
applies depends on the kind of override:

**Data attributes - No:**
The block sets every `data-*` itself, from its App block settings and the resolved discount. Adding `data-*` to your own markup has no effect on a block instance; they're the configuration surface for the [web component](/docs/components/volume-picker/web-component/) only. To change block behaviour, use its [settings](/docs/components/volume-picker/app-block/).

**CSS styling tokens — Yes:**
They're CSS custom properties that inherit through the shadow boundary, so they style a block exactly like a web component. The block's colour / radius / spacing pickers just write the matching setting-backed tokens into a scoped `<style>` rule for you. Any token **not** exposed as a setting (e.g. `--dkl-vp-legend-spacing`, `--dkl-vp-list-gap`) you can still set yourself from your own CSS — `:root`, the embed's **Custom CSS** field, or a rule targeting the block.

**CSS parts and classes — Yes:**
The shadow DOM and light-DOM markup are identical, so `::part()` and the `.dkl-volume-picker__*` classes work the same on a block or a web component.
:::

:::tip[Token precedence]
A token the block writes from a chosen setting is scoped to the block's id (`#dkl-vp-{block.id}`),
which is more specific than a `:root` rule — so to override *that* token, either change the editor
setting or match the specificity (target the block element). Tokens the block leaves unset fall back to your CSS or
the built-in default as normal.
:::

## Data attributes

Set as `data-*` on the host. On a web component the carrier supplies the data attributes; the
behaviour toggles default off.

#### `data-discount-id`

`metaobject handle` · default: `carrier (first eligible)`

Which discount's carrier to clone. The `discount-` prefix is optional; an attribute-less
tag uses the default (first eligible).

#### `data-style`

`"cards" | "mini-buttons"` · default: `cards`

Presentation: stacked cards, or a compact button grid (the per-tier price line is hidden).

#### `data-money-format`

`string` · default: `carrier (shop.money_format)`

Money format for JS-reformatted prices.

#### `data-widget-id`

`string` · default: `null`

Instance id; disambiguates multiple widgets.

#### `data-update-price-on-change`

`"true" | "false"` · default: `false`

Whether selecting a tier updates the displayed price — the theme's native price element and
the [`<dkl-price>`](/docs/components/price/overview/) component (via the tier-change event's
`updatesPrice` flag). When `false`, the event still fires for custom integrations, but no
price display reflects the tier.

#### `data-price-target`

`CSS selector | "none"` · default: `auto-detect`

Override or disable the price element target. Use `"none"` when pairing with
[`<dkl-price>`](/docs/components/price/overview/).

#### `data-sync-with-quantity`

`"true" | "false"` · default: `false`

Sync the theme's quantity selector to the selected tier's quantity.

#### `data-quantity-target`

`CSS selector | "none"` · default: `auto-detect`

Override or disable the quantity input target.

#### `data-quantity-event`

`event name` · default: `(none)`

An extra theme event to also drive quantity sync, on top of `quantity-selector:update`.
The component reads the quantity from the event's `detail.quantity`, or re-reads the form
input if absent.

#### `data-exclude-sale-prices`

`"true" | "false"` · default: `carrier (the discount's excludeSale)`

Disable tiers when the variant is already on sale.

#### `data-price-unavailable-label`

`string` · default: `No discount available`

Label shown when a tier is unavailable.

:::note
**Sold-out variants disable the tiers** (on initial render and on variant change),
independently of `data-exclude-sale-prices` — a selectable tier on a variant the form
won't add would be a dead end.
:::

<details>
<summary>Per-tier attributes (data-dkl-*)</summary>

Server-rendered onto each `input.dkl-volume-picker__radio`; the component reads them. You
don't set these by hand — they're listed for reference.

#### `data-dkl-tier-index`

`int`

The tier's position in the group.

#### `data-dkl-discount-type`

`"percentage" | "fixedAmount"`

How the tier's discount is expressed.

#### `data-dkl-discount-amount`

`number`

The fixed discount amount (when `fixedAmount`).

#### `data-dkl-discount-percent`

`number`

The discount percent (when `percentage`).

#### `data-dkl-unit-price-cents`

`int (cents)`

The pre-computed discounted unit price.

</details>

## CSS styling tokens

    ![Image highlighting the CSS styling tokens for the DKL Volume Picker component](/images/components/dkl-volume-css-tokens.jpg)
    *CSS styling tokens for the DKL Volume Picker component - layout: cards*
    ![Image highlighting the CSS styling tokens for the DKL Volume Picker component](/images/components/dkl-volume-mini-css-tokens.jpg)
    *CSS styling tokens for the DKL Volume Picker component - layout: mini-buttons*

Two layers: a shadow `<style>` for the title/list structure, and the light-DOM card chrome
in the stylesheet. The card chrome mostly consumes the
[global brand tokens](/docs/components/overview/#global-brand-tokens) so cards match the theme.

### Structure

#### `--dkl-vp-legend-spacing`

default: `0.75rem`

Space below the title row.

#### `--dkl-vp-title-font-weight`

default: `600`

Group title font weight.

#### `--dkl-vp-title-font-size`

default: `0.95rem`

Group title font size.

#### `--dkl-vp-title-color`

default: `inherit`

Group title color.

#### `--dkl-vp-list-gap`

default: `0.5rem`

Gap between options.

#### `--dkl-vp-count`

default: `tier count (max 3)`

Mini-buttons grid columns.

#### `--dkl-vp-mini-padding`

default: `0.375rem 1rem`

Mini-buttons option padding.

#### `--dkl-vp-selected-border-color`

default: `#000000`

Border and ring of the **selected** tier.

#### `--dkl-color-border`

default: `rgba(0,0,0,.12)`

Resting card border.

#### `--dkl-radius`

default: `8px`

Card corners.

#### `--dkl-color-background`

default: `#fff`

Card background.

#### `--dkl-color-background-soft`

default: `rgba(0,0,0,.04)`

Hover background.

#### `--dkl-color-accent`

default: `#217a4a`

Focus-visible outline.

## CSS parts and classes

The title/list scaffold is in shadow DOM (parts); the radio cards are slotted light DOM
(classes).

### Parts

    ![Image highlighting the CSS parts for the DKL Volume Picker component](/images/components/dkl-volume-css-parts.jpg)
    *CSS parts for the DKL Volume Picker component - layout: cards*
    ![Image highlighting the CSS parts for the DKL Volume Picker component - layout: mini-buttons](/images/components/dkl-volume-mini-css-parts.jpg)
    *CSS parts for the DKL Volume Picker component - layout: mini-buttons*

#### `root`

`CSSPart`

The `<fieldset>` wrapper.

#### `legend-wrapper`

`CSSPart`

The title row.

#### `title`

`CSSPart`

The `<legend>` group title.

#### `list`

`CSSPart`

The radiogroup holding the options.

### Light-DOM classes

#### `.dkl-volume-picker__option`

`class`

One tier card (selected: `:has(.dkl-volume-picker__radio:checked)`).

#### `.dkl-volume-picker__radio`

`class`

The radio input.

#### `.dkl-volume-picker__content`

`class`

Card inner row.

#### `.dkl-volume-picker__header`

`class`

Title + discount stack.

#### `.dkl-volume-picker__title`

`class`

Tier heading (e.g. "Buy 3+").

#### `.dkl-volume-picker__discount`

`class`

The "X% off each" line.

#### `.dkl-volume-picker__price`

`class`

Per-tier price.

#### `.dkl-volume-picker__price-unit`

`class`

The unit suffix (e.g. "/ea").

#### `.dkl-volume-picker__price-unavailable`

`class`

"No discount" placeholder.

## Examples

```css title="Recolour the selected card border"
:root {
  --dkl-vp-selected-border-color: #2563eb;
}
```

```css title="Tighter list, bolder titles"
:root {
  --dkl-vp-list-gap: 0.25rem;
  --dkl-vp-title-font-weight: 700;
}
```

```html title="Compact button layout"
<dkl-volume-picker-radio-groups
  data-style="mini-buttons"
  style="--dkl-vp-mini-padding: 0.25rem 0.75rem;"
></dkl-volume-picker-radio-groups>
```

## Next steps

---

# Web Component

Source: https://discountkit.app/docs/components/volume-picker/web-component/

A web component is the `<dkl-volume-picker-radio-groups>` tag written directly into your
theme's Liquid. On a **product page** it needs **zero attributes** — it clones a pre-staged
carrier and renders the picker server-side.

## Usage

On a product page, add the `<dkl-volume-picker-radio-groups>` web component — it renders the first eligible `PRODUCT_VOLUME` discount server-side:

```html
<dkl-volume-picker-radio-groups></dkl-volume-picker-radio-groups>
```

It renders the first eligible `PRODUCT_VOLUME` discount server-side — including the
light-DOM radio cards, which join the product form. If the product has **no** eligible
volume discount, no carrier exists and the tag hides itself.

### Multiple volume discounts on one product

Each eligible discount has its own carrier, keyed by its discount id. An attribute-less tag
clones the **first** eligible discount; `data-discount-id` targets a specific one (the
`discount-` prefix is optional). Place one tag per discount to show several — they can't
collide:

```html
<dkl-volume-picker-radio-groups data-discount-id="1478638797012"></dkl-volume-picker-radio-groups>
<dkl-volume-picker-radio-groups data-discount-id="discount-1478638797013"></dkl-volume-picker-radio-groups>
```

## Reacting to changes

`<dkl-volume-picker-radio-groups>` emits `discount-kit-live:volume-discount:tier-change`
when a tier is selected or deselected. To run your own code on a tier change, listen for
that event — it bubbles, so you can listen on `document`. See the
[Events](/docs/components/volume-picker/events/) page for the full payload shape, and
[Listen for tier changes](#examples) in the examples below for a working listener.

## Examples

For the full list of `data-*` attributes you can set, see
[Styling & Data Attributes](/docs/components/volume-picker/styling-and-data/).

```html title="Override attributes + tokens"
<dkl-volume-picker-radio-groups
  data-discount-id="1478638797012"
  data-style="mini-buttons"
  data-update-price-on-change="true"
  data-sync-with-quantity="true"
  style="
    --dkl-vp-selected-border-color: #2563eb;
    --dkl-vp-list-gap: 0.25rem;
    --dkl-vp-title-font-weight: 700;
    --dkl-radius: 12px;
  "
></dkl-volume-picker-radio-groups>
```

```html title="Pair with <dkl-price>"
<!-- Let <dkl-price> own the price; the picker only emits events -->
<dkl-volume-picker-radio-groups data-price-target="none"></dkl-volume-picker-radio-groups>
<dkl-price></dkl-price>
```

```js title="Listen for tier changes"
// Bubbles, so you can listen on document
document.addEventListener(
  'discount-kit-live:volume-discount:tier-change',
  (event) => {
    const { productId, currentTier, previousTier } = event.detail.resource

    if (!currentTier) {
      console.log('Tier cleared — back to base price')
      return
    }

    console.log(
      `Product ${productId}: tier ${currentTier.index} — ` +
        `buy ${currentTier.quantity} at ${currentTier.unitPriceCents}c each`
    )
  }
)
```

```js title="Example event payload"
// event.detail.resource on tier-change
{
  productId: 7820000000001,
  variantId: 41200000000001,
  widgetId: 'volume-picker-12345-cards',
  widgetType: 'volume-picker-radio-groups',
  previousTier: {
    index: 0,
    quantity: 2,
    discountAmount: 5,
    discountType: 'percentage',
    unitPriceCents: 1900
  },
  currentTier: {
    index: 1,
    quantity: 3,
    discountAmount: 10,
    discountType: 'percentage',
    unitPriceCents: 1800
  }
}
```

## Next steps

---

# Common settings

Source: https://discountkit.app/docs/discounts/common-settings/

#### Method and Title/Code

Determines whether the discount will be applied automatically or at checkout via a discount code.

#### Customer context

Every discount type includes an **Eligibility** card — powered by Shopify's native discount context — for controlling who a discount applies to. Choose one of:

- **All customers** _(default)_ — no eligibility restriction.
- **Customer segments** — restrict the discount to one or more [Shopify customer segments](https://help.shopify.com/manual/customers/customer-segmentation/customer-segments).
- **Markets** — restrict the discount to one or more of your [Shopify markets](https://help.shopify.com/manual/markets).

These options are **mutually exclusive** — a discount can target customer segments _or_ markets, but not both at the same time. This mirrors Shopify's native discount context.

:::note
When eligibility is limited to **Customer segments** or **Markets**, Discount Kit Live storefront components can't operate with the discount. Keep eligibility set to **All customers** if you rely on storefront display.
:::

:::tip
The **Eligibility** card targets the full range of your Shopify markets. The separate [Market eligibility](#market-eligibility) option in the sidebar targets **regional** markets only — reach for the Eligibility card when you need to target customer segments or non-regional markets.
:::

#### Customer eligibility

Restricts the discount for use only by customer accounts that possess specific tags.

:::tip
For [Custom discounts](/docs/discounts/custom/), you can also set customer tag conditions at the proposal level for more granular control.
:::

#### Market eligibility

Restricts the discount for use only in specific **regional** markets. To target customer segments or the full range of your Shopify markets, use the [Customer context](#customer-context) Eligibility card instead.

:::tip
For [Custom discounts](/docs/discounts/custom/), you can also set market conditions at the proposal level to target different markets with different offers.
:::

#### Location eligibility

Restricts the discount for use only at specific retail/POS locations.

:::tip
For [Custom discounts](/docs/discounts/custom/), you can also set location conditions at the proposal level for location-specific promotions.
:::

#### B2B eligibility

Controls whether B2B (company) customers can use the discount.

By default, discounts only apply to regular (B2C) customers. Toggle on **B2B** to include company customers, then choose from:

- **All customers (B2B + B2C)** - Both company buyers and regular customers can use the discount
- **B2B only** - Restricts the discount exclusively to company buyers

:::tip
Use "B2B only" when you want to offer exclusive pricing or promotions to your wholesale or business customers without affecting your retail pricing. Combine with [customer tag conditions](#customer-eligibility) to precision target specific B2B buyers, such as VIP accounts or particular company tiers.
:::

#### Currency

Alters the discount so that it calculates and applies discounts based on a specific currency rather than the store's base currency.

#### Cart attribute

Restricts the discount to only apply when a specific [cart attribute](https://shopify.dev/docs/api/liquid/objects/cart#cart-attributes) is present. Cart attributes are custom key/value pairs attached to a cart, typically set by your theme or a third-party app.

- **Key only** — The discount applies whenever the attribute key exists on the cart, regardless of its value.
- **Key + value** — The discount applies only when the attribute key is present **and** its value matches exactly.

:::tip
This is useful for gating discounts behind app-controlled conditions. For example, a loyalty app could set a `loyalty_level` attribute, and you could restrict a discount to carts where `loyalty_level` is `"vip"`.
:::

#### Recurring payments for subscriptions

Determines whether the discount will apply on subsequent subscription orders.

#### Maximum discount uses

Restricts either total discount usage or prevents customers from using the code more than once. These options are only available when the discount method is set to discount code.

#### Combinations

Determines how the discount combines with other discounts. Pick which classes (Product / Order / Shipping) this discount can stack with, and — on Shopify Plus — which tags allow it to stack with other product discounts on the **same cart line**.

See [Stacking discounts](/docs/discounts/stacking/) for the full picture, including cart-line stacking via tags.

#### Tags

Label the discount with one or more tags (up to 5). Tags drive two things:

- **Cart-line stacking** — two product discounts can apply to the same cart line if they share a tag in each other's cart-line combination list. See [Stacking discounts](/docs/discounts/stacking/) for the full pattern.
- **Filtering and bulk actions** — find or bulk-edit discounts by tag from the discounts list (e.g. all `BFCM` discounts).

Tags are merchant-defined free text. Pick a vocabulary that means something to your team (`SEASONAL`, `LOYALTY`, `BFCM`, `VIP`) and reuse it consistently — autocomplete suggests tags you've used on other discounts.

#### Active dates

Determines the dates and times that the discount will be active between.

---

# Custom

Source: https://discountkit.app/docs/discounts/custom/

## Setup

1. **Open your store's Discounts page and click Create discount**

   ![Create new discount image](/images/create-new-discount.png)

2. **Scroll down to the Discount Kit section, which should now be available, and click Custom**

   ![Select custom image](/images/select-custom.png)

3. **Configure your desired settings and click Save**

   ![Save custom image](/images/save-custom.png)

## Settings

### Overview

Custom discounts allow you to create advanced discount rules that go beyond standard Shopify discounting. With this feature, you can return multiple product discount proposals and control exactly how they get applied to cart lines in an order.

A discount proposal consists of several key components:

1. **Cart groups** - Define which products to include in your rules
2. **Conditions** - Specify when your discount should apply
3. **Targets** - Select which products receive the discount
4. **Qualifiers** - Create "Buy X, Get Y" style offers with repeating patterns
5. **Bundle pricing** - Offer fixed prices for sets of items (e.g., "3 for $25")
6. **Consume** - Prevent discounted items from being used by subsequent rules
7. **Value** - Determine how much discount to apply

Each component works together to create powerful, flexible discount scenarios that can handle complex business requirements.

#### Selection Strategy

Once you've created multiple discount proposals, you can choose a selection strategy to determine which ones get applied:

- **First matching discount** - Applies the first valid discount that matches all conditions
- **Maximum discount** - Applies the discount that offers the largest total savings
- **All discounts** - Applies all valid discounts simultaneously

This approach gives you precise control over discount application, ensuring customers receive exactly the right offer.

### Cart Groups

A Cart group is a powerful way to define which products you want to include in your discount rules. Think of it as creating a "bucket" of products that match specific criteria you set.

#### What is a cart group?

A Cart group lets you define a specific set of products based on various filters. Once created, you can use these groups in your discount conditions, prerequisites, or targets.

#### How cart groups work

When you create a Cart group, you can apply multiple filters to narrow down exactly which products should be included. A product must match all selected filters to be included in the group.

Available filters

- **Products**: Select specific products/variants to include
- **Collections**: Include products from specific collections
- **Line quantity**: Match products with at least a certain quantity in the cart
- **Line price**: Match products with at least a certain price
- **Line attribute**: Filter by custom attributes assigned to products
- **Metafield value**: Filter products by their metafield values
- **Purchase type**: Include one-time purchases, subscriptions, or both
- **Compare-at price**: Include products that have a compare-at price

You can select as many, or as few cart group filters. Remember that a product must match all selected filters to be included in a Cart group, allowing for precise targeting of your discount rules.

#### When to use cart groups

Cart groups are useful when:

- You want to create discounts that apply only to specific product combinations
- You need to set up prerequisites that require customers to buy certain items first
- You want to exclude certain products from discount eligibility

### Conditions

#### What are Discount Conditions?

Conditions are rules that determine when your discount should be applied. They act as "true or false" statements that evaluate a customer's cart and eligibility criteria.

#### How Conditions Work

When creating a discount rule, you can add multiple conditions. All conditions must be true for the discount to apply. This means conditions are combined with an "AND" relationship - if any single condition fails, the entire discount will not be applied.

Conditions are organized into two categories:

- **Cart conditions** - Evaluate the contents of the customer's cart
- **Eligibility conditions** - Evaluate customer and context criteria

#### Cart Condition Types

Cart conditions refer to a Cart Group and can check:

| Condition | Description |
|-----------|-------------|
| **Quantity** | Number of items from the group in the cart |
| **Total** | Total purchase amount from items in the group |
| **Unique Products** | Number of different products from the group |
| **Unique Variants** | Number of different variants from the group |
| **Unique Groups** | Number of selected groups with at least one item in the cart (spans multiple groups, ≥ 2 required) |

Most cart conditions support operators like "equals", "greater than", "less than", "at least", and "at most" for flexible matching. **Unique Groups** supports "at least".

#### Unique Groups condition

The **Unique Groups** condition differs from the others: instead of evaluating a single Cart Group, it counts how many of a selected list of Cart Groups have at least one item in the cart. It answers the question "buy from at least N of these groups, get the discount."

Use it when your offer rewards customers for spanning multiple product categories rather than buying a certain quantity of any one item. A common pattern is a **Routine Builder** for skincare or haircare:

- Cart Group: **Cleanse** (any cleanser)
- Cart Group: **Treat** (any serum or treatment)
- Cart Group: **Moisturise** (any moisturiser)
- Cart Group: **Protect** (any SPF/sunscreen)

You can stack tiered offers across multiple discount proposals:

- Proposal 1: 10% off when the cart contains items from **2** of the 4 groups
- Proposal 2: 15% off when the cart contains items from **3** of the 4 groups
- Proposal 3: 20% off when the cart contains items from **all 4** groups

With the **Maximum discount** [Selection Strategy](#selection-strategy), the customer automatically gets the qualifying proposal that offers the largest total savings. This works well for tiers that discount comparable targets.

:::note
The minimum group count is **2 or higher**, and the rule must list **at least 2** Cart Groups. A single-group rule would be equivalent to a regular Quantity condition, so the Unique Groups condition always spans multiple groups.
:::

#### Eligibility Condition Types

Eligibility conditions allow you to control who can receive each discount proposal:

| Condition | Description | Operators |
|-----------|-------------|-----------|
| **Market** | Target specific Shopify markets | "is any", "is none" |
| **Customer Tags** | Target customers with specific tags | "is any", "is none", "is all", "is logged in customer" |
| **Location** | Target specific retail/POS locations | "is any", "is none" |

:::note
Eligibility conditions set on a discount proposal work alongside the discount-level settings in [Common Settings](/docs/discounts/common-settings/). Both must be satisfied for the discount to apply.
:::

#### Per-Proposal Eligibility

A key feature of Custom discounts is the ability to set different eligibility conditions on each discount proposal. This allows you to:

- Create a single Custom discount with proposals targeting different markets
- Offer different deals to customers based on their tags within the same discount
- Configure location-specific offers for retail POS scenarios

For example, you could have:
- Proposal 1: 20% off for customers in the US market
- Proposal 2: 15% off for customers in the EU market
- Proposal 3: 25% off for VIP-tagged customers in any market

All within a single Custom discount configuration.

#### When to Use Conditions

Use **cart conditions** when you want to create discounts that only apply in specific situations, such as:

- When a customer has at least 3 items from a specific collection
- When a customer spends at least $100 on qualifying products
- When a customer has selected at least 2 different products from your new arrivals

Use **eligibility conditions** when you want to:

- Offer different discount values to different markets
- Target specific customer segments with unique offers
- Create location-specific promotions for retail stores

Conditions give you precise control over when discounts should be valid.

### Targets

#### What are discount targets?

Targets determine which products receive the discount. These are the cart lines that will have their prices reduced when the discount conditions are met.

#### How targets work

Each target refers to a Cart Group. You can add multiple targets to a discount rule, and you can control whether:

**All targets must be present** - Every target group must have matching products in the cart.

For each target, you can also specify a quantity. This determines how many items from that group should receive the discount.

Targets give you precise control over which products receive discounts.

### Qualifiers (Buy X, Get Y)

#### What are qualifiers?

Qualifiers define what customers must purchase before receiving a discount. They create the "Buy" part of "Buy X, Get Y" promotions.

#### How qualifiers work

When you add qualifiers to a discount rule, it becomes a repeating discount. The discount is applied once for each set of qualifying items in the cart.

For example, if your qualifier is "Buy 2 shirts" and a customer has 6 shirts in their cart, the discount can be applied up to 3 times.

Qualifiers always refer to a Cart Group. You can add multiple qualifiers that reference different groups to create more complex promotions, such as "Buy 1 shirt AND 1 pair of pants, get 20% off accessories".

#### Controlling maximum repeats

You can limit how many times the discount repeats by setting a **maximum repeats** value. If left blank, the discount repeats as many times as the cart allows.

#### Example: Buy 2, Get 1 Free

1. Create a Cart Group called "Shirts" that includes your shirt collection
2. Add a qualifier: "Shirts", quantity 2
3. Add a target: "Shirts", quantity 1
4. Set the value to 100% off

A customer with 9 shirts would receive 3 free shirts (3 sets of "buy 2, get 1").

### Bundle Pricing

#### What is bundle pricing?

Bundle pricing lets you offer a fixed price for a set of items — for example, "3 for $25". Unlike Buy X Get Y promotions, bundle pricing does not require separate qualifying items. Instead, the target items themselves form the bundle.

#### How bundle pricing works

To create a bundle price:

1. Add one or more **targets** with a quantity
2. Enable **Repeat** on the discount rule
3. Set the value to a **fixed price**

The discount automatically calculates how many complete bundles can be formed from the items in the cart and applies the fixed price to each bundle.

#### Example: 3 for $25

1. Create a Cart Group called "T-Shirts" with your t-shirt collection
2. Add a target: "T-Shirts", quantity 3
3. Enable Repeat
4. Set the value to fixed price $25

A customer with 7 t-shirts (normally $15 each) would get 2 bundles at $25 each (6 shirts) plus 1 shirt at full price — total $65 instead of $105.

#### Maximum repeats

You can limit how many bundles a customer can receive by setting a maximum repeats value. If left blank, the discount creates as many bundles as the cart allows.

### Consume

#### What is consume mode?

Consume mode prevents discounted items from being targeted by subsequent discount rules within the same Custom discount. When enabled, items that receive a discount from one rule are "consumed" and removed from the pool of available items for later rules. Only the discounted items (targets) are consumed — qualifying items remain available.

#### How consume mode works

Without consume mode, all discount rules evaluate against the full cart independently. This means the same item could be targeted by multiple rules.

With consume mode enabled, rules are evaluated in order. Once an item is discounted by a rule, it is removed from the pool. Later rules can only target the remaining items. Qualifying items (the "Buy X" part of a Buy X Get Y rule) are not consumed and remain available for subsequent rules.

#### Example

Consider a Custom discount with two rules and consume mode **enabled**:
- Rule 1: "Buy 2 Get 1 Free" on shirts
- Rule 2: "10% off" all shirts

If a customer has 9 shirts:
1. Rule 1 applies 3 times (2 qualifying + 1 free per bundle) — 3 shirts are free and consumed
2. Rule 2 applies 10% off to the remaining 6 shirts (the qualifying shirts from Rule 1)

With consume mode **disabled**, Rule 2 would apply 10% off to all 9 shirts in addition to the 3 free shirts from Rule 1.

#### When to use consume mode

Use consume mode when:

- You have multiple rules that target overlapping products and want to prevent double-discounting
- You want to prioritize one offer over another (earlier rules get priority)
- You're combining "Buy X, Get Y" with a fallback discount for remaining items

:::note
Consume mode only works with the **All discounts** selection strategy. When using First matching or Maximum discount strategies, consume mode is automatically disabled since Shopify selects winners after the function returns.
:::

### Values

The custom discount allows you to specify discount values in a few different ways:

- **Percentage off** - Reduce the price by a percentage (e.g., 20% off)

- **Amount off** - Reduce the price by a fixed amount (e.g., $10 off)

- **Fixed price** - Set a specific price for the item (e.g., $5 each)

#### Amount off

Allows you to specify a monetary amount to be spread across all qualifying items, or optionally applied to each qualifying item.

#### Fixed price

Sets a specific price regardless of the original item price. It is only available for repeating discount rules

#### Apply to compare at price

You can optionally target the compare-at price of targets when applying discounts. Here, discount values are dynamically calculated based off the compare-at price, rather than the actual price of the product. Note, only the 'difference' between the desired discount, and the already discounted value will be applied.

### Metafield Configuration

Discount Kit's product and variant metafield 'Metafield Discount' configuration allows you to specify information that can be used inside the Custom Discount. The configuration must be structured as an array:

```
type CustomData = {
  discount_title: String // required - used to match configurations to specific discounts
  tag?: String // optional, and used only in the 'grouping' mechanism
  discount_message?: String // optional, defaults to discount title
  discount_percentage?: number // optional, 1-100
  discount_value?: number // optional, amount off in cents, 100 = $1 off
  discount_fixed_price?: number // optional, target price in cents, 2500 = $25.00
}

type CustomDatas = CustomData[] // array is required
```

:::note
Only one of `discount_percentage`, `discount_value`, or `discount_fixed_price` should be set per entry. If multiple are provided, `discount_fixed_price` takes priority, followed by `discount_value`, then `discount_percentage`.
:::

The `discount_fixed_price` field sets the item to a specific price by discounting the difference between the current price and the target price. For example, if a product costs $40 and `discount_fixed_price` is set to `2500` (i.e. $25.00), a $15 discount will be applied. If the current price is already at or below the fixed price, no discount is applied.

The schema also allows additional custom properties (e.g. `discount_badge`) which are not used by the discount function but can be read by theme code or other integrations.

This configuration is wrapped by a discount. This means you get all of the other benefits of a Discount Kit discount (manual or automatic codes, scheduling, targeting specific customers, targeting specific markets), but can change the discounted variants, their values and their messaging at any time!

You must provide an array of configurations, with each configuration specifying a matching `discount_title`. This allows you to define different discount behaviors for different Custom discounts. If you specify multiple configurations for the same discount, only the first matching configuration will be used.

![Example metafield configuration with array format](/images/metafield-datas.png)

## Integrations

There are no integrations for the Custom discount out of the box. However, take a look at [Discount Kit Live](/docs/live/introduction/) for ideas on how to build your own!

---

# Gift with purchase

Source: https://discountkit.app/docs/discounts/gift-with-purchase/

## Setup

1. **Open your store's Discounts page and click Create discount**

   ![Create new discount image](/images/create-new-discount.png)

2. **Scroll down to the Discount Kit section, which should now be available, and click Gift with purchase**

   ![Select gift with purchase image](/images/select-gwp.png)

3. **Fill in the desired settings and click Save**

   ![Save gift with purchase image](/images/save-gwp.png)

## Settings

#### Condition type

Determines the type of cart condition that must be met before the discount will apply. The options are either a set quantity of products or a monetary amount.

#### Value type

Determines the type of discount that will be applied. The options are either a fixed amount off or a percentage.

#### Applies to

Determines whether the discount will apply to all products, a selection of products, or a collection.

#### Purchase Type

Determines if the discount applies to only subscription products, one-time purchase products, or both.

#### Exclude products with compare-at prices

This option will exclude products with compare-at prices from tier prerequisite totals. This is particularly useful when targeting a collection with the discount.

#### Group by

Determines how the discount will group the products before applying tier rules. Mix-and-match means that all products will count together toward each tier. Product and product variant options will apply tiers to each product or variant separately, allowing for products to have different discounts applied.

### Tiers

#### Title override

Overrides the discount title when the discount is displayed in the cart or checkout. Optional.

#### Minimum quantity/minimum subtotal

Determines the number of products, or total product value, required to apply the discount.

#### Percentage off/Fixed amount off

Determines the discount value that will be applied.

## Integrations

#### Automatic Gifts

Open your store's **theme editor**. Select **App embeds** in the left hand panel and then enable **Gift with purchase** from Discount Kit. Open up **Gift with purchase**'s settings using the drop-down arrow and select **Automatically add single variant gift products to the cart**.

**Page Refresh Option:**

In most cases, it's best to enable **Refresh page after making cart changes** so that customer's carts do not become out of sync with the store's theme.

However, if you prefer to handle cart updates yourself (for a smoother user experience), you can disable this option.

:::caution[Important]
If you disable page refresh, you MUST manually update/refresh the cart UI in your theme code. Failing to do so can cause the cart to get out of sync, leading to incorrect discount calculations and other issues.
:::

**Manually Refreshing the Cart:**

If you disable page refresh, use this code to update your cart after gift adjustments:

```javascript
document.addEventListener('discount_kit:cart_changed', () => {
  // Update/re-render your theme's ajax cart here
});
```

Once enabled, once a customer has unlocked a Gift with Purchase discount tier that contains a single product variant it will automatically be added to the cart. For gift tiers that contain multiple variants and the customer needs to choose from among them see instructions for enabling the Gift Selector below.

![Auto gift setup image](/images/auto-gift-setup.png)

**Allowing shoppers to remove gifts:**

You can allow shoppers to manually remove automatically added gifts without them being re-added to the cart. This is useful when a shopper doesn't want a particular gift, even though they've qualified for it.

To enable this feature, open the **Gift with purchase** settings in your theme editor's App embeds section and enable **Don't re-add manually removed gifts**.

![Don't re-add manually removed gifts setting](/images/manually-removed-gift.png)

With this setting enabled, if a shopper manually removes an automatically added gift from their cart, it will not be re-added again.

#### Gift Selector

To let customers choose their gift when multiple variants are available, enable **Enable gift selector** in the **Gift with purchase** settings. You can customize the gift selector's appearance using the styling options below this setting.

![Gift selector setup image](/images/gift-selector-setup.png)

#### Custom Integration

For developers building custom gift experiences, Discount Kit dispatches a browser event containing gift adjustment data:

**Event Name:** `discount_kit:gift_adjustments`

This event provides a list of gift products to add to, and cart lines to remove from, the cart as a result of changes to the cart.

**Event Structure:**

```typescript
{
  add: {
    discountId: string,
    discountTitle: string,
    quantity: number,
    options: {
      id: string,
      image: string,
      priceRange: {
        min: number,
        max: number
      },
      title: string,
      variants: {
        available: boolean,
        id: string,
        title: string,
        image: string | null,
        price: number
      }[]
    }[]
  },
  remove: {
    [lineKey]: 0
  }
}
```

**Important:** For the `remove` property to work correctly, you must add a line item property to gifted products:
- Key: `_dk_gift`
- Value: `<discount_title>`

The `remove` property in the event will include any cart line with the `_dk_gift` property that does not contain an active discount.

**Example Usage:**

```javascript
document.addEventListener('discount_kit:gift_adjustments', (event) => {
  const { add, remove } = event.detail;

  // Add gifts to cart
  if (add.options.length > 0) {
    // Handle gift selection/addition
  }

  // Remove old gifts
  Object.keys(remove).forEach(lineKey => {
    // Remove cart line by key
  });
});
```

---

# Localized messages

Source: https://discountkit.app/docs/discounts/localized-messages/

For all automatic discounts, you can override discount messages with translations for all your store's published locales. This allows you to display discount information to customers in their preferred language.

## How to add translated overrides

1. **Create or edit an automatic discount**

   Navigate to your discount configuration and ensure the discount method is set to Automatic.

2. **Find the title override field**

   Scroll to the tier settings where you can set an override title.

3. **Click the translate button**

   ![Translate button](/images/localise-button.png)

   Click the translate button that appears inside the title override field.

4. **Choose a language**

   ![Localise menu](/images/localise-menu.png)

   A menu opens listing every published locale. A checkmark next to a language means a translation is already set. Click the language you want to edit.

5. **Enter your translated override**

   The field switches to that locale, with the locale code shown as a prefix. Type your translated message. Repeat from the previous step for each language you want to support.

6. **Save your changes**

   Click Save to apply your changes.

## Limitations

The following discount configurations cannot be localized:

- **Manual discount codes**: Localization is only available for automatic discounts. Manual codes use a single title across all locales.
- **Discount code titles**: When using the discount code method, the code itself and its title cannot be translated.

---

# Order

Source: https://discountkit.app/docs/discounts/order-volume/

## Setup

1. **Open your store's Discounts page and click Create discount**

   ![Create new discount image](/images/create-new-discount.png)

2. **Scroll down to the Discount Kit section, which should now be available, and click Order goal**

   ![Select order goal image](/images/select-order-goal.png)

3. **Configure your desired settings and click Save**

   ![Save order goal image](/images/save-order-goal.png)

## Settings

#### Value Type

Denotes the type of discount that will be applied, either a percentage or fixed amount, to the order.

### Discount application

#### Exclude a specific collection

You can exclude products from a specific collection from counting towards thresholds or receiving discounts.

![Exclude collection interface](/images/exclude-collection.png)

#### Exclude products with compare at prices

Allows for excluding products with compare at prices from both the prerequisite count and discount.

:::caution
Using exclusions (either collection or sale items) limits this discount to 1 tier due to a technical limitation on the Shopify side.
:::

### Tiers

Allows for the merchant to give varying discount amounts based on different cart values. Discounts are not cumulative, and thus each tier will replace the discount value of the previous tier.

#### Title override

This will be displayed instead of the discount title in the cart if specified. Currently only works for automatic discounts.

#### Minimum subtotal

Specifies the minimum value required in the cart to unlock the tier.

#### Percentage/Fixed amount off

Specifies the discount value that will be applied to the cart.

## Integrations

#### Order Goal Banner

Open your store's **Theme Editor** and then head to the **cart** page. On the left-hand side, click **Add block**. Under **Apps**, select **Order Goal Banner**.

This component displays the remaining spend amount needed to achieve the next tier in an active Order Goal discount.

![Setup order goal banner image](/images/order-goal-banner-setup.png)

---

# Product volume

Source: https://discountkit.app/docs/discounts/product-volume/

## Setup

1. **Open your store's Discounts page and click Create discount**

   ![Create new discount image](/images/create-new-discount.png)

2. **Scroll down to the Discount Kit section, which should now be available, and click Product volume**

   ![Select product volume image](/images/select-product-volume.png)

3. **Configure your desired settings and click Save**

   ![Save product volume image](/images/save-product-volume.png)

## Settings

#### Condition type

Determines the type of cart condition that must be met before the discount will apply. The options are either a set quantity of products or a monetary amount.

#### Value type

Determines the type of discount that will be applied. The options are either a fixed amount off or a percentage.

#### Applies to

Determines whether the discount will apply to all products, a selection of products, or a collection.

#### Purchase Type

Determines if the discount applies to only subscription products, one-time purchase products, or both.

#### Exclude products with compare-at prices

This option will exclude products with compare-at prices from tier prerequisite totals. This is particularly useful when targeting a collection with the discount.

#### Group by

Determines how the discount will group the products before applying tier rules. Mix-and-match means that all products will count together toward each tier. Product and product variant options will apply tiers to each product or variant separately, allowing for products to have different discounts applied.

### Tiers

#### Title override

Overrides the discount title when the discount is displayed in the cart or checkout. Optional.

#### Minimum quantity/minimum subtotal

Determines the number of products, or total product value, required to apply the discount.

#### Percentage off/Fixed amount off

Determines the discount value that will be applied.

## Integrations

#### Product Volume Table

Head to your **theme editor** and then to the **product** page. On the left-hand side, click **Add block** to add the **Product Volume Table**.<br /><br />

This is a purely informational component that informs customers of an available discount as well as where they sit within that discount for the current page's product.

![Volume table setup image](/images/setup-volume-table.png)

#### Bundle Selector

As above, on the **product** page in your **theme editor**, click **Add block** and select the **Bundle Selector** from available app blocks.

This component gives customers the ability to quickly add a selection of products to satisfy an available discount. For the sake of clarity, it could be best to create a product page specific to products with discounts and remove the default variant picker and quantity selector components for that page. The Bundle Selector will handle all of that for you!

![Bundle selector setup image](/images/setup-bundle-selector.png)

---

# Stacking discounts

Source: https://discountkit.app/docs/discounts/stacking/

By default, Shopify allows **one discount per class** at checkout: one product discount, one order discount, and one shipping discount. Stacking lets multiple discounts apply to the same cart in two dimensions:

- **Across classes** — combine a product discount with an order discount, a shipping discount, or all three.
- **On the same cart line** — apply two product discounts to the same line item (e.g. seasonal sale + loyalty perk).

Both dimensions are configured in the **Combinations** card on the discount editor.

## Discount classes

Every discount belongs to one or more classes:

| Class | What it discounts |
|---|---|
| **Product** | Specific cart line items (e.g. 20% off T-shirts) |
| **Order** | The whole order subtotal (e.g. $10 off any order over $100) |
| **Shipping** | Shipping rates (e.g. free shipping on orders over $75) |

A discount of class X can combine with discounts of any class — including its own — except shipping. Two shipping discounts can never apply to the same shipment.

## Combining across classes

In the **Combinations** card, check the classes this discount should combine with. The other discount also has to opt in: combining is only allowed when **both** discounts list each other's class.

:::tip
Combinations are mutual. If you add a 20% off Order discount and a Free Shipping discount, both must check the other's class for them to apply together.
:::

## Combining on the same cart line

:::note
This feature is only available on **Shopify Plus** plans.
:::

By default, only one product discount applies to any given cart line. If a customer has both "20% off T-shirts" and "Buy 2, get 1 free" eligible for the same shirt, only the better-value discount wins.

To stack two product discounts on the same line, both discounts must:

1. **Be tagged** with one or more shared tag (e.g. `SEASONAL`).
2. **Opt in to combining on that tag** in the Combinations card.

When this discount and another product discount share a tag in their cart-line lists, both apply to the same line.

### Example — seasonal sale + loyalty bonus

You're running a seasonal 15% off sale on outerwear and want to layer a 5% loyalty bonus on top for VIP customers.

| Discount | Tags | Cart-line combines with |
|---|---|---|
| **Seasonal sale** (15% off jackets) | `SEASONAL`, `LOYALTY` | `LOYALTY` |
| **VIP loyalty bonus** (5% off everything for VIPs) | `LOYALTY` | `SEASONAL` |

Both discounts list `LOYALTY` (or `SEASONAL`) on the other's tags, so they stack. A VIP customer who buys a jacket gets 15% + 5% on the same line.

### How tags work in cart-line stacking

- Tags are **set on the discount itself** (in the [Tags](/docs/discounts/common-settings/#tags) card in the editor).
- The cart-line list in **Combinations** says "I'll stack on a line with another product discount that has any of these tags."
- The match is **bidirectional** — both discounts must list a tag the other has.
- Up to **5 tags** per cart-line list.

### Order of application

When multiple product discounts stack on the same cart line, Shopify applies them in a fixed order:

1. **Percentage discounts before fixed-amount discounts.**
2. **Within each group, highest economic value first** — the discount worth the most applies before the discount worth less.

:::note
This ordering is Shopify checkout behavior we've observed. It isn't currently documented by Shopify, and it's not something Discount Kit — or any app — can control or configure. It may change without notice.
:::

## Stacking and Discount Kit Live

[Discount Kit Live](/docs/live/introduction/) writes scalar metafields like `max_reward_percent` that reflect the **best individual discount** for a product. Stacked discounts are not pre-computed in Live's metafields — the actual stacked total only resolves at checkout.

If your storefront badging or pricing copy depends on the post-stack total, render it from the cart object at runtime rather than from the product-level Live metafields.

---

# Introduction

Source: https://discountkit.app/docs/documentation/

Discount Kit allows you to craft complex and advanced discount experiences for your Shopify store. Create volume discounts, BOGO offers, order goals, customer-specific pricing, and market segmentation - then display them beautifully in your storefront with **Discount Kit Live**.

All discount types are Shopify discount functions, which means they integrate with your theme out of the box, and you inherit the stability and performance of Shopify's infrastructure. Really, you can think of Discount Kit as extending Shopify's native discounts!

## Get Started

---

# Percentage discount rounding

Source: https://discountkit.app/docs/general/percentage-discount-rounding/

If a percentage discount produces a total that's a few cents — or sometimes a few dollars — off what you'd expect, the cause is almost always **per-unit rounding**.

Shopify calculates percentage discounts on a **per-unit** basis, rounds the result to the currency's smallest denomination (one cent for USD), and then multiplies by the line quantity. When the discount per unit doesn't divide evenly into cents, that rounding compounds with quantity.

## How it works

For a line with quantity `Q`, unit price `P`, and percentage `D%`:

1. Per-unit discount = `P × (D / 100)`
2. Rounded to cents → call this `r`
3. Total discount = `r × Q`
4. Line total = `(P × Q) − (r × Q)`

If `P × (D / 100)` is already a clean number of cents, the result matches the "naive" `subtotal × D%` calculation exactly. Otherwise, the per-unit rounding gets multiplied by `Q`, so larger quantities make the gap more visible.

## Worked examples

### 10% off 200 × $0.23

- Per-unit discount: `$0.23 × 0.10 = $0.023` → rounds to **$0.02 / unit**
- Total discount: `200 × $0.02 = $4.00`
- Line total: `$46.00 − $4.00 = $42.00`

Expected from `$46.00 × 0.90` would be `$41.40` — a **$0.60 difference**, caused by the 0.3¢-per-unit rounding × 200 units.

### 15% off 300 × $0.23

- Per-unit discount: `$0.23 × 0.15 = $0.0345` → rounds to **$0.03 / unit**
- Total discount: `300 × $0.03 = $9.00`
- Line total: `$69.00 − $9.00 = $60.00`

Expected from `$69.00 × 0.85` would be `$58.65` — a **$1.35 difference**, caused by the 0.45¢-per-unit rounding × 300 units.

## When you'll notice it

The gap is most visible when:

- The unit price is low (cents and tens-of-cents)
- The quantity is high
- The percentage produces a sub-cent fraction per unit (10% of $0.23, 15% of $0.27, etc.)

For typical retail prices ($10–$500) and modest quantities, the difference is usually 0–1¢ per line and easy to miss.

## How to get an exact total

If you need the discounted total to exactly match `subtotal × (1 − D%)`:

- **Use a fixed amount discount** instead of a percentage. A fixed amount is applied to the line as a whole rather than per unit.
- **Choose a unit price and percentage that divide cleanly into cents.** For example, 10% off $0.20 ($0.02 / unit) is exact at any quantity, but 10% off $0.23 is not.
- **Sell in larger units.** A 6-pack at $1.38 with 10% off ($0.138 → $0.14 per pack) still rounds, but the relative impact at typical quantities is much smaller than per-unit-of-$0.23.

:::tip
This rounding is applied by Shopify's checkout, not by Discount Kit. The same
per-unit allocation behaviour applies to native Shopify percentage discounts
as well.
:::

---

# Share discount logs

Source: https://discountkit.app/docs/general/share-discount-logs/

If your discounts aren't performing as you expect, sharing discount logs helps our support team diagnose and resolve issues quickly.

1. **Click the overflow menu and select Manage app**

   ![Manage app menu](/images/manage-app.png)

2. **Scroll to the bottom and click Share logs**

   ![Share logs button](/images/share-logs.png)

---

# Examples

Source: https://discountkit.app/docs/live/examples/

## Quick Start: Best Discount Badge

The simplest way to show a discount badge using the `max_reward_percent` or `max_reward_cents` scalar metafields.

![Product card with red '20% OFF' badge in top-right corner](/images/examples/simple-percentage-badge.webp)

```liquid
{% assign percent_off = product.metafields.app--9549316097--discount_kit.max_reward_percent.value %}
{% assign cents_off = product.metafields.app--9549316097--discount_kit.max_reward_cents.value %}

{% if percent_off or cents_off %}
  <div style="
    position: absolute;
    top: 10px;
    right: 10px;
    background: #e74c3c;
    color: white;
    padding: 8px 12px;
    border-radius: 4px;
    font-size: 12px;
    font-weight: bold;
  ">
    {% if percent_off %}
      {{ percent_off | round }}% OFF
    {% else %}
      {{ cents_off | divided_by: 100.0 | money }} OFF
    {% endif %}
  </div>
{% endif %}
```

:::tip
This approach is simpler than parsing the full discounts array and automatically shows the **best** available discount.
:::

---

### Best Discount with Title

Show both the discount value and title using `max_reward_discount`:

```liquid
{% assign percent_off = product.metafields.app--9549316097--discount_kit.max_reward_percent.value %}
{% assign best_discount = product.metafields.app--9549316097--discount_kit.max_reward_discount.value %}

{% if percent_off and best_discount %}
  <div class="promo-banner">
    <strong>{{ best_discount.discount_title }}</strong>
    <span>Save {{ percent_off | round }}%</span>
  </div>
{% endif %}
```

---

## Sales Badges

### Simple Percentage Badge

![Product card with red '20% OFF' badge in top-right corner](/images/examples/simple-percentage-badge.webp)

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% if discounts.size > 0 %}
  {% assign discount = discounts | first %}
  <div style="
    position: absolute;
    top: 10px;
    right: 10px;
    background: #e74c3c;
    color: white;
    padding: 8px 12px;
    border-radius: 4px;
    font-size: 12px;
    font-weight: bold;
  ">
    {{ discount.maximum_reward_value | round }}% OFF
  </div>
{% endif %}
```

---

## Pricing Display

### Crossed-Out Original Price

![Product pricing showing original price crossed out in gray and sale price in red](/images/examples/crossed-out-price.webp)

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% if discounts.size > 0 %}
  {% assign discount = discounts | first %}

  {% if discount.reward_type == 'PERCENTAGE' %}
    {% assign discount_percent = discount.maximum_reward_value %}
    {% assign discount_multiplier = 100 | minus: discount_percent | times: 0.01 %}
    {% assign discounted_price = product.price | times: discount_multiplier %}

    <div class="pricing">
      <span class="original-price" style="text-decoration: line-through; opacity: 0.6;">
        {{ product.price | money }}
      </span>
      <span class="sale-price" style="color: #e74c3c; font-weight: bold;">
        {{ discounted_price | money }}
      </span>
    </div>
  {% else %}
    <span class="regular-price">{{ product.price | money }}</span>
  {% endif %}
{% else %}
  <span class="regular-price">{{ product.price | money }}</span>
{% endif %}
```

---

## Volume Pricing Table

![Product with info icon next to title and volume pricing popup showing quantity tiers and discounted prices](/images/examples/volume-pricing-table.webp)

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% if discount.discount_type == 'PRODUCT_VOLUME' and discount.config %}
    {% assign config = discount.config.value %}

    <div class="volume-table">
      <h4>{{ discount.discount_title }}</h4>
      <table>
        <thead>
          <tr>
            <th>Quantity</th>
            <th>Discount</th>
            <th>Price Each</th>
          </tr>
        </thead>
        <tbody>
          {% for tier in config.tiers %}
            {% assign tier_qty = tier.buys.value %}
            {% assign tier_discount_percent = tier.gets.value %}
            {% assign discount_multiplier = 100 | minus: tier_discount_percent | divided_by: 100.0 %}
            {% assign tier_price = product.price | times: discount_multiplier %}

            <tr>
              <td>{{ tier_qty }}+</td>
              <td>{{ tier_discount_percent | round }}% off</td>
              <td>{{ tier_price | money }}</td>
            </tr>
          {% endfor %}
        </tbody>
      </table>
    </div>
  {% endif %}
{% endfor %}
```

---

## Discount Codes

Discount Kit Live surfaces both **automatic** discounts (applied at checkout when conditions are met) and **code-based** discounts (the shopper enters a code). The `method` and `code` fields let you render the right UI for each.

### Render a Code Chip with Copy-to-Clipboard

For code-based discounts, show the code with a copy button instead of an "applied automatically" badge.

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% if discount.method == 'code' and discount.code != blank %}
    <div class="discount-code-chip">
      <strong>{{ discount.discount_title }}</strong>
      <span>Use code:</span>
      <button
        type="button"
        data-discount-code="{{ discount.code | escape }}"
        onclick="navigator.clipboard.writeText(this.dataset.discountCode); this.textContent = 'Copied!'">
        {{ discount.code }}
      </button>
    </div>
  {% endif %}
{% endfor %}
```

:::tip
Use `<button>` rather than rendering the code as plain text so it's keyboard-accessible. Set `data-discount-code` from Liquid so the copy handler reads the raw value (not the visible label, which you may want to obfuscate or shorten).
:::

### Hide a Code If It's Already Applied

Once a shopper has the code in their cart, the chip is just noise. Check `cart.discount_applications` to detect already-applied codes and hide the chip accordingly.

`cart.discount_applications` is a Shopify-native array of every discount currently affecting the cart. Each entry has a `title` (for automatics) or a `code` (for `DiscountCodeApplication` entries). For code discounts you compare against `application.code`.

```liquid
{%- comment -%}
  Build a Set-like map of code strings currently applied to the cart.
  Liquid doesn't have Sets, so we use a comma-joined string and `contains`.
{%- endcomment -%}
{% capture applied_codes %}
  {%- for application in cart.discount_applications -%}
    {%- if application.type == 'discount_code' -%},{{ application.code | downcase }},{%- endif -%}
  {%- endfor -%}
{% endcapture %}

{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% if discount.method == 'code' and discount.code != blank %}
    {% assign needle = ',' | append: discount.code | downcase | append: ',' %}
    {% unless applied_codes contains needle %}
      <div class="discount-code-chip">
        <strong>{{ discount.discount_title }}</strong>
        <span>Use code <code>{{ discount.code }}</code></span>
      </div>
    {% endunless %}
  {% endif %}
{% endfor %}
```

:::note
The `,` wrappers around each code prevent partial matches: e.g. `SALE` shouldn't match `SUMMERSALE10`. The comparison is `downcase`d on both sides because Shopify treats discount codes case-insensitively at checkout.
:::

### Mix: Auto-Applied vs Code-Entry Badge

Render different UI depending on how the discount is redeemed:

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% if discount.method == 'automatic' %}
    <span class="badge badge--auto">
      {{ discount.maximum_reward_value | round }}% off — auto-applied
    </span>
  {% elsif discount.method == 'code' and discount.code != blank %}
    <span class="badge badge--code">
      {{ discount.maximum_reward_value | round }}% off with code
      <code>{{ discount.code }}</code>
    </span>
  {% endif %}
{% endfor %}
```

---

## Collection Banners

### Simple Collection Promo

![Collection page with red banner displaying 'PLANTS DISCOUNT Save up to 20% on this collection!'](/images/examples/simple-collection-promo.webp)

```liquid
{% assign discounts = collection.metafields.app--9549316097--discount_kit.discounts.value %}

{% if discounts.size > 0 %}
  {% assign promo = discounts | first %}

  <div style="
    background: #e74c3c;
    color: white;
    padding: 1rem 2rem;
    border-radius: 4px;
    text-align: center;
    margin-bottom: 2.5rem;
    display: flex;
    align-items: center;
    justify-content: center;
    gap: 1.5rem;
  ">
    <h2 style="
      font-size: 1.8rem;
      font-weight: 700;
      margin: 0;
      line-height: 1;
      text-transform: uppercase;
      letter-spacing: 0.05em;
    ">{{ promo.discount_title }}</h2>
    <p style="
      font-size: 1.6rem;
      margin: 0;
      line-height: 1;
    ">Save up to {{ promo.maximum_reward_value | round }}% on this collection!</p>
  </div>
{% endif %}
```

---

## Next Steps

    title="Data reference"
    description="Complete field documentation"
    href="/docs/live/reference/"
  />
    title="Introduction"
    description="Learn about Discount Kit Live"
    href="/docs/live/introduction/"
  />

---

# Filtering discounts

Source: https://discountkit.app/docs/live/filtering-discounts/

Discount Kit Live surfaces up to 25 of the discounts you've tagged `dk:live` — both automatic and code-based. It doesn't filter by who's viewing the page, what market they're in, or what's already in their cart. Use these inline Liquid patterns to do that filtering in your theme.

:::note
The `max_reward_percent` and `max_reward_cents` scalar metafields automatically exclude targeted discounts (test mode, GWP, customer-tagged, market-specific, and code-based). If you use the scalar metafields for badges, no filtering is needed. The patterns below are only needed when working with the full `discounts` array.
:::

## Filtering by Method (Automatic vs Code)

Each discount in the `discounts` array carries a `method` field of either `'automatic'` or `'code'`. Split your rendering accordingly:

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{%- comment -%} Auto-applied discounts: render plain badges {%- endcomment -%}
{% for discount in discounts %}
  {% if discount.method == 'automatic' %}
    <span class="badge">{{ discount.maximum_reward_value | round }}% OFF</span>
  {% endif %}
{% endfor %}

{%- comment -%} Code discounts: render code chips with copy button {%- endcomment -%}
{% for discount in discounts %}
  {% if discount.method == 'code' and discount.code != blank %}
    <span class="code-chip">
      {{ discount.maximum_reward_value | round }}% off with <code>{{ discount.code }}</code>
    </span>
  {% endif %}
{% endfor %}
```

## Hiding Codes Already Applied to the Cart

When a shopper has already entered a discount code, advertising it again is noise. Compare the code against `cart.discount_applications` to detect what's in play:

```liquid
{%- comment -%}
  Build a lookup of applied codes once. Liquid has no Sets, so we use a
  comma-joined string and `contains`. Comma wrappers prevent partial matches
  (e.g. `SALE` shouldn't match `SUMMERSALE10`).
{%- endcomment -%}
{% capture applied_codes %}
  {%- for application in cart.discount_applications -%}
    {%- if application.type == 'discount_code' -%},{{ application.code | downcase }},{%- endif -%}
  {%- endfor -%}
{% endcapture %}

{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% if discount.method == 'code' and discount.code != blank %}
    {% assign needle = ',' | append: discount.code | downcase | append: ',' %}
    {% unless applied_codes contains needle %}
      <span class="code-chip">Use <code>{{ discount.code }}</code></span>
    {% endunless %}
  {% endif %}
{% endfor %}
```

:::note
Shopify normalises discount codes case-insensitively at checkout, so we `downcase` both sides of the comparison. The `cart.discount_applications` array is populated server-side on each page render, so this works without any JavaScript.
:::

## Filtering Test Mode Discounts

Discounts in test mode only apply to customers tagged `test`. Use the `test` field to exclude them from your storefront display.

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% for discount in discounts %}
  {% unless discount.test %}
    <div class="badge">
      {{ discount.maximum_reward_value | round }}% OFF
    </div>
  {% endunless %}
{% endfor %}
```

## Filtering by Market

Discounts can be restricted to specific Shopify Markets. Filter to show only those applicable to the customer's current market.

### How It Works

- Uses `localization.market.handle` to identify the current market
- Empty `included_markets` means the discount applies to all markets
- If `included_markets` has values, the current market must match
- Checks `excluded_markets` to exclude specific markets

### Complete Example

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}
{% assign current_market = localization.market.handle %}
{% assign eligible_discount = nil %}

{% for discount in discounts %}
  {% assign is_eligible = true %}

  {% comment %} Check included markets {% endcomment %}
  {% if discount.included_markets.size > 0 %}
    {% assign market_match = false %}
    {% for market in discount.included_markets %}
      {% if market == current_market %}
        {% assign market_match = true %}
        {% break %}
      {% endif %}
    {% endfor %}
    {% unless market_match %}
      {% assign is_eligible = false %}
    {% endunless %}
  {% endif %}

  {% comment %} Check excluded markets {% endcomment %}
  {% if discount.excluded_markets.size > 0 %}
    {% for market in discount.excluded_markets %}
      {% if market == current_market %}
        {% assign is_eligible = false %}
        {% break %}
      {% endif %}
    {% endfor %}
  {% endif %}

  {% comment %} Take first eligible discount {% endcomment %}
  {% if is_eligible %}
    {% assign eligible_discount = discount %}
    {% break %}
  {% endif %}
{% endfor %}

{% if eligible_discount %}
  <div class="badge">
    {{ eligible_discount.maximum_reward_value }}% OFF
  </div>
{% endif %}
```

## Filtering by Customer Tags

Discounts can target specific customers using tags. Filter to show only those applicable to the current customer.

### How It Works

- **Included Tags**: Customer must have at least one tag from `included_customer_tags`
- **Excluded Tags**: Customer must not have any tag from `excluded_customer_tags`
- **Not Logged In**: Customers who aren't logged in are excluded from tag-targeted discounts

### Complete Example

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}
{% assign eligible_discount = nil %}

{% for discount in discounts %}
  {% assign is_eligible = true %}

  {% comment %} Check included customer tags {% endcomment %}
  {% if discount.included_customer_tags.size > 0 %}
    {% if customer %}
      {% assign has_required_tag = false %}
      {% for required_tag in discount.included_customer_tags %}
        {% if customer.tags contains required_tag %}
          {% assign has_required_tag = true %}
          {% break %}
        {% endif %}
      {% endfor %}
      {% unless has_required_tag %}
        {% assign is_eligible = false %}
      {% endunless %}
    {% else %}
      {% comment %} Not logged in but tags required {% endcomment %}
      {% assign is_eligible = false %}
    {% endif %}
  {% endif %}

  {% comment %} Check excluded customer tags {% endcomment %}
  {% if discount.excluded_customer_tags.size > 0 %}
    {% if customer %}
      {% for excluded_tag in discount.excluded_customer_tags %}
        {% if customer.tags contains excluded_tag %}
          {% assign is_eligible = false %}
          {% break %}
        {% endif %}
      {% endfor %}
    {% endif %}
  {% endif %}

  {% comment %} Take first eligible discount {% endcomment %}
  {% if is_eligible %}
    {% assign eligible_discount = discount %}
    {% break %}
  {% endif %}
{% endfor %}

{% if eligible_discount %}
  <div class="vip-badge">
    {{ eligible_discount.discount_title }}
  </div>
{% endif %}
```

## Combined Filtering

Combine both market and customer tag checks for complete eligibility filtering:

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}
{% assign current_market = localization.market.handle %}
{% assign eligible_discount = nil %}

{% for discount in discounts %}
  {% assign is_eligible = true %}

  {% comment %} Check market eligibility {% endcomment %}
  {% if discount.included_markets.size > 0 %}
    {% assign market_match = false %}
    {% for market in discount.included_markets %}
      {% if market == current_market %}
        {% assign market_match = true %}
        {% break %}
      {% endif %}
    {% endfor %}
    {% unless market_match %}
      {% assign is_eligible = false %}
    {% endunless %}
  {% endif %}

  {% if discount.excluded_markets.size > 0 %}
    {% for market in discount.excluded_markets %}
      {% if market == current_market %}
        {% assign is_eligible = false %}
        {% break %}
      {% endif %}
    {% endfor %}
  {% endif %}

  {% comment %} Check customer tag eligibility {% endcomment %}
  {% if is_eligible and discount.included_customer_tags.size > 0 %}
    {% if customer %}
      {% assign has_required_tag = false %}
      {% for required_tag in discount.included_customer_tags %}
        {% if customer.tags contains required_tag %}
          {% assign has_required_tag = true %}
          {% break %}
        {% endif %}
      {% endfor %}
      {% unless has_required_tag %}
        {% assign is_eligible = false %}
      {% endunless %}
    {% else %}
      {% assign is_eligible = false %}
    {% endif %}
  {% endif %}

  {% if is_eligible and discount.excluded_customer_tags.size > 0 %}
    {% if customer %}
      {% for excluded_tag in discount.excluded_customer_tags %}
        {% if customer.tags contains excluded_tag %}
          {% assign is_eligible = false %}
          {% break %}
        {% endif %}
      {% endfor %}
    {% endif %}
  {% endif %}

  {% if is_eligible %}
    {% assign eligible_discount = discount %}
    {% break %}
  {% endif %}
{% endfor %}

{% if eligible_discount %}
  <div class="badge">
    {{ eligible_discount.maximum_reward_value }}% OFF
  </div>
{% endif %}
```

## Next Steps

- Learn how to [access discount data](/docs/live/storefront-data/)
- View complete [examples](/docs/live/examples/)
- Check the full [reference](/docs/live/reference/)

---

# Introduction

Source: https://discountkit.app/docs/live/introduction/

DiscountKit Live syncs the discounts you choose to your Shopify storefront,
making them available through metafields for instant access — no API calls,
no performance overhead.

## How it works

DiscountKit Live is **opt-in**. You decide which discounts the storefront sees
by tagging them with `dk:live` in Shopify's discount editor — the same Tags
field you use for anything else. This works for both **automatic discounts**
and **discount codes** (manual codes), created in DiscountKit or anywhere else
in your admin.

- **To include** a discount in DiscountKit Live: add the tag `dk:live`.
- **To exclude** a discount: remove the tag.

Once a discount is tagged, the **Refresher** syncs it to your storefront
within seconds. Discount data is available through metafields at three levels
— products, collections, and shop-wide — all using the namespace
`app--9549316097--discount_kit` and key `discounts`.

:::note[Migrating from the old behaviour?]
When the tag-gated model first goes live for your shop, DiscountKit
automatically applies the `dk:live` tag to every currently-active automatic
discount, so nothing drops out of your storefront on rollout. After that
one-time migration, the tag is yours to manage — add or remove it like any
other tag to control what surfaces in DiscountKit Live.
:::

## Discount limits

DiscountKit Live surfaces **up to 25 tagged discounts in total** on each
refresh. That's a hard ceiling combining both automatic and code-based
discounts, driven by Shopify's underlying limit on the discount nodes query.

- Shopify allows at most 25 *active automatic* discounts on a shop, so
  historically the 25 cap was effectively invisible.
- With code-based discounts supported, the cap matters: if you tag 5 automatic
  + 30 code discounts with `dk:live`, only 25 of them will appear in
  DiscountKit Live on each refresh. Untag the ones you don't need surfaced.

### Collection fan-out

Discounts targeting collections are automatically **fanned out** to every
product in those collections. This means a product's metafields include all
applicable discounts — both those targeting the product directly and those
inherited from its collections.

For example, if you create a "Summer Sale" discount on the "T-Shirts"
collection, every product in that collection will have the discount in its
`discounts` metafield. You don't need to check the collection metafield
separately — product badges just work.

The same applies to `max_reward_percent`, `max_reward_cents`, and
`max_reward_discount` — these scalar metafields reflect the best discount
across both direct and collection-inherited discounts.

## Key features

- **Merchant-controlled** — opt in or out per discount via the `dk:live` tag
- **Automatic + code discounts** — surface both auto-applied and code-redeemed discounts
- **No API calls** — data is already on the page via metafields
- **Real-time updates** — changes sync within seconds of tag/untag
- **Zero latency** — instant access, even on collection pages with 100+ products
- **Server-rendered** — available during initial page render
- **Active discounts only** — expired or paused discounts are excluded
- **Quick access values** — scalar metafields for the best discount (`max_reward_percent`, `max_reward_cents`)

## Limitations and restrictions

While DiscountKit Live provides powerful storefront access to discount data,
there are some known limitations:

**Scalar metafields only reflect universal discounts:**

The `max_reward_percent`, `max_reward_cents`, and `max_reward_discount` scalar
metafields only reflect discounts that apply to **all visitors** without
conditions. The following discount types are excluded from scalar computation:

- **Test mode** discounts
- **GWP** (Gift With Purchase) discounts
- **Customer-tagged** discounts (targeting specific customer tags)
- **Market-specific** discounts (targeting specific markets)
- **Code-based** discounts (require the shopper to enter a code; advertising
  them in a "Save up to X%" badge would over-promise to shoppers who don't
  know the code)

These discounts still appear in the full `discounts` array, where you can
filter them in Liquid. Use the scalar metafields for simple, drop-in badges
that work for all visitors.

**Collection fan-out product limit:**

When discounts target collections, DiscountKit Live resolves every product in
those collections and writes metafields to each one. This fan-out is currently
limited to a maximum of **8,000 unique products** across all collection-based
discounts. Products beyond this limit will still receive the correct discount
at checkout, but may not display badges or strike-through pricing on the
storefront. This limit will be increased in a future update.

**Customer segments:**

Shopify's native automatic discounts support targeting by **customer
segments** (dynamically updated customer groups based on behavior, purchase
history, etc.). Unfortunately, Shopify does not currently expose customer
segment information in Liquid templates.

This means:

- Discounts using customer segments will work correctly at checkout
- However, DiscountKit Live cannot filter these discounts in the storefront
  based on segment membership
- Workaround: use **customer tags** instead, which are supported in Liquid and
  work with DiscountKit Live

If you need to show segment-specific discounts in your storefront, consider
using customer tags as an alternative targeting method.

## Next steps

Read [Storefront data](/docs/live/storefront-data/) to learn how to access
discount data in your theme, then dig into [Settings](/docs/live/settings/),
the full [data reference](/docs/live/reference/), and the guides on
[filtering discounts](/docs/live/filtering-discounts/) and worked
[examples](/docs/live/examples/).

---

# Data reference

Source: https://discountkit.app/docs/live/reference/

## Quick Access Metafields

For simple badge displays, use these scalar metafields instead of parsing the full discount array:

:::note
Both `max_reward_percent` and `max_reward_cents` are always present, but only one will have a non-zero value. Percentage discounts are always preferred over fixed amounts. When a product or collection has no active discounts, both values are `0`.
:::

:::caution
These scalar metafields only reflect **universal discounts** — discounts that apply to all visitors without conditions. The following discount types are excluded from scalar computation:

- **Test mode** discounts (`test: true`)
- **GWP** (Gift With Purchase) discounts — 100% off on gifts is misleading as a badge
- **Customer-tagged** discounts — only apply to specific customers
- **Market-specific** discounts — only apply in certain markets
- **Code-based** discounts (`method: 'code'`) — the shopper has to enter the code first

These discounts still appear in the full `discounts` array where you can filter them in Liquid. Use the scalar metafields for simple, drop-in badges that work for all visitors.
:::

### max_reward_percent
**Type:** `number_decimal`

The best percentage discount value available for this product/collection.

```liquid
{% assign percent_off = product.metafields.app--9549316097--discount_kit.max_reward_percent.value %}

{% if percent_off %}
  <span class="badge">{{ percent_off | round }}% OFF</span>
{% endif %}
```

### max_reward_cents
**Type:** `number_integer`

The best fixed amount discount in cents. Set to `0` when a percentage discount is available instead.

```liquid
{% assign cents_off = product.metafields.app--9549316097--discount_kit.max_reward_cents.value %}

{% if cents_off %}
  <span class="badge">{{ cents_off | divided_by: 100.0 | money }} OFF</span>
{% endif %}
```

### max_reward_discount
**Type:** `metaobject_reference`

Reference to the full DiscountSummary metaobject for the best discount. Use this to access additional details like `discount_title` or `discount_type`.

```liquid
{% assign best = product.metafields.app--9549316097--discount_kit.max_reward_discount.value %}

{% if best %}
  <div class="promo">
    <strong>{{ best.discount_title }}</strong>
  </div>
{% endif %}
```

---

## DiscountSummary Fields

Every discount in Discount Kit Live is represented as a **DiscountSummary** metaobject with these fields:

---

## Core Fields

### discount_title
**Type:** `string`

The customer-facing discount name.

```liquid
{{ discount.discount_title }}
{%- comment -%} "Buy More Save More" {%- endcomment -%}
```

### discount_type
**Type:** `string`

The type of discount.

| Value | Description |
|-------|-------------|
| `PRODUCT_VOLUME` | Volume/tiered pricing |
| `ORDER_GOAL` | Cart-wide order discounts |
| `GWP` | Gift with purchase |
| `BXGY` | Buy X Get Y (native Shopify) |
| `BASIC` | Basic discount (native Shopify) |
| `FREE_SHIPPING` | Free shipping (native Shopify) |
| `SHIPPING` | Shipping discounts |
| `CUSTOM` | Custom discount logic |
| `UNKNOWN_APP` | Discount from another app |

```liquid
{% if discount.discount_type == 'PRODUCT_VOLUME' %}
  <span>Volume Discount</span>
{% endif %}
```

---

## Threshold Fields

What customers need to **buy** to qualify.

### threshold_type
**Type:** `string`

How the threshold is measured: `QUANTITY`, `AMOUNT`, or `NONE`

```liquid
{% if discount.threshold_type == 'QUANTITY' %}
  <p>Buy {{ discount.minimum_threshold_value | floor }} items</p>
{% elsif discount.threshold_type == 'AMOUNT' %}
  <p>Spend {{ discount.minimum_threshold_value | divided_by: 100.0 | money }}</p>
{% endif %}
```

### minimum_threshold_value
**Type:** `number`

Minimum quantity or amount (in cents) to qualify.

```liquid
{{ discount.minimum_threshold_value }}
```

### threshold_product_references
**Type:** `list.product_reference`

Products that count toward the threshold.

```liquid
{% for product_ref in discount.threshold_product_references %}
  {{ product_ref.title }}
{% endfor %}
```

### threshold_collection_references
**Type:** `list.collection_reference`

Collections that count toward the threshold.

```liquid
{% for collection_ref in discount.threshold_collection_references %}
  {{ collection_ref.title }}
{% endfor %}
```

---

## Reward Fields

What discount customers **receive**.

### reward_type
**Type:** `string`

Discount type: `PERCENTAGE`, `FIXED_AMOUNT`, or `FIXED_PRICE`.

- `PERCENTAGE` – percentage off (e.g., `20` = 20% off)
- `FIXED_AMOUNT` – fixed discount amount in cents (e.g., `500` = $5 off)
- `FIXED_PRICE` – fixed final price in cents (e.g., `1500` = $15 final price)

```liquid
{% if discount.reward_type == 'PERCENTAGE' %}
  {{ discount.maximum_reward_value }}% OFF
{% elsif discount.reward_type == 'FIXED_AMOUNT' %}
  ${{ discount.maximum_reward_value | divided_by: 100.0 }} OFF
{% elsif discount.reward_type == 'FIXED_PRICE' %}
  Now ${{ discount.maximum_reward_value | divided_by: 100.0 }}
{% endif %}
```

### minimum_reward_value
**Type:** `number`

Lowest discount value (first tier).

### maximum_reward_value
**Type:** `number`

**Highest discount value (top tier).** Most commonly used field!

```liquid
<div class="badge">
  {{ discount.maximum_reward_value }}% OFF
</div>
```

### reward_product_references
**Type:** `list.product_reference`

Products that receive the discount.

### reward_collection_references
**Type:** `list.collection_reference`

Collections that receive the discount.

---

## Method & Opt-in Fields

How the discount is redeemed, and the tags it carries.

### method
**Type:** `string`

How the customer redeems the discount: `'automatic'` or `'code'`.

- `automatic` — applied automatically when the cart meets the discount's conditions.
- `code` — requires the shopper to enter the code stored in [`code`](#code).

Use this to render the right UI in your storefront — a "20% off" badge for automatics, a code chip with a copy button for codes.

```liquid
{% if discount.method == 'code' %}
  <span class="discount-code">Use code <code>{{ discount.code }}</code></span>
{% else %}
  <span class="discount-auto">Applied at checkout</span>
{% endif %}
```

### code
**Type:** `string`

The discount code the shopper enters at checkout. Empty for automatic discounts. For code discounts with multiple codes, only the first/primary code is exposed.

```liquid
{% if discount.code != blank %}
  <button data-copy="{{ discount.code }}">Copy "{{ discount.code }}"</button>
{% endif %}
```

### tags
**Type:** `list.single_line_text_field`

All tags currently applied to the discount in Shopify, including `dk:live`. Useful for grouping discounts in custom storefront UI (e.g. surface "vip" or "seasonal" tagged discounts in dedicated sections).

```liquid
{%- comment -%} Tags include 'dk:live' plus anything the merchant added. {%- endcomment -%}
{% if discount.tags contains 'vip' %}
  <span class="vip-only">VIP exclusive</span>
{% endif %}
```

:::note
Every discount surfaced in Discount Kit Live is, by definition, tagged `dk:live` — so checking for that tag in Liquid is redundant. Use the `tags` field for *additional* merchant-defined tags.
:::

---

## Targeting Fields

Who can use it and where it applies.

### included_customer_tags
**Type:** `list.single_line_text_field`

Customer tags that qualify. Empty = all customers.

```liquid
{% if discount.included_customer_tags.size > 0 %}
  {% assign first_tag = discount.included_customer_tags | first %}
  {% if customer.tags contains first_tag %}
    <span class="vip-badge">VIP ONLY</span>
  {% endif %}
{% endif %}
```

### excluded_customer_tags
**Type:** `list.single_line_text_field`

Customer tags that don't qualify.

### included_markets
**Type:** `list.single_line_text_field`

Market handles where this applies. Empty = all markets.

```liquid
{% if discount.included_markets.size > 0 %}
  <p>Available in: {{ discount.included_markets | join: ', ' | upcase }}</p>
{% endif %}
```

### excluded_markets
**Type:** `list.single_line_text_field`

Markets where this doesn't apply.

### currency
**Type:** `string`

Specific currency code (e.g., `USD`). Empty = all currencies.

```liquid
{% if discount.currency %}
  <small>{{ discount.currency }} only</small>
{% endif %}
```

### allow_b2b
**Type:** `boolean | null`

Whether B2B (company) customers can use this discount. `null` for native Shopify or unknown app discounts — treat `null` as unrestricted (same as `false`). Use `unless` rather than `== false` in Liquid to correctly handle both `null` and `false`.

### only_b2b
**Type:** `boolean | null`

Whether this discount is restricted exclusively to B2B customers. `null` for native Shopify or unknown app discounts — treat `null` as unrestricted (same as `false`).

```liquid
{% comment %} Correct: matches both false and null {% endcomment %}
{% unless discount.only_b2b %}
  <small>Available to all customers</small>
{% endunless %}
```

### cart_attribute_key
**Type:** `string`

Cart attribute key required for the discount to apply. Empty = no cart attribute requirement.

```liquid
{% if discount.cart_attribute_key != blank %}
  <small>Requires cart attribute: {{ discount.cart_attribute_key }}</small>
{% endif %}
```

### cart_attribute_value
**Type:** `string`

Cart attribute value that must match exactly. Empty = any value is accepted (presence-only check).

```liquid
{% if discount.cart_attribute_key != blank and discount.cart_attribute_value != blank %}
  <small>Requires {{ discount.cart_attribute_key }}: {{ discount.cart_attribute_value }}</small>
{% endif %}
```

---

## Tier-Level Fields

Detailed per-tier data for building dynamic storefront UIs like progress bars, tier tables, and gift selectors.

:::note
These fields are arrays where each index corresponds to a tier. For example, `thresholds[0]` is the first tier's threshold value.
:::

### thresholds
**Type:** `list.number_integer`

Threshold values for each tier. Values are in **cents** for amount-based thresholds, or **quantity** for quantity-based thresholds.

```liquid
{% assign tier_thresholds = discount.thresholds.value %}

{% for threshold in tier_thresholds %}
  {% if discount.threshold_type == 'QUANTITY' %}
    <li>Buy {{ threshold }} items</li>
  {% else %}
    <li>Spend {{ threshold | divided_by: 100.0 | money }}</li>
  {% endif %}
{% endfor %}
```

### reward_values
**Type:** `list.number_integer`

Reward values for each tier. Values are:

- **percentages** when `reward_type` is `PERCENTAGE` (e.g., `10` = 10%)
- **discount amounts in cents** when `reward_type` is `FIXED_AMOUNT` (e.g., `500` = $5 off)
- **final prices in cents** when `reward_type` is `FIXED_PRICE` (e.g., `1500` = $15 final price)

```liquid
{% assign rewards = discount.reward_values.value %}

{% for reward in rewards %}
  {% if discount.reward_type == 'PERCENTAGE' %}
    <span>{{ reward }}% OFF</span>
  {% elsif discount.reward_type == 'FIXED_AMOUNT' %}
    <span>{{ reward | divided_by: 100.0 | money }} OFF</span>
  {% elsif discount.reward_type == 'FIXED_PRICE' %}
    <span>Now {{ reward | divided_by: 100.0 | money }}</span>
  {% endif %}
{% endfor %}
```

### reward_quantities
**Type:** `list.number_integer`

For GWP (Gift With Purchase) discounts, the number of free items per tier. Empty for non-GWP discounts.

```liquid
{% assign quantities = discount.reward_quantities.value %}

{% if quantities.size > 0 %}
  <p>Get {{ quantities[current_tier] }} free gift(s)!</p>
{% endif %}
```

### reward_product_indexes
**Type:** `json`

Maps each tier to available reward product indexes. Structure: `[[tier0_indexes], [tier1_indexes], ...]`

Each index references a product in `reward_product_references`.

```liquid
{% assign product_indexes = discount.reward_product_indexes.value %}
{% assign reward_products = discount.reward_product_references.value %}

{%- comment -%} Show products available at tier 1 {%- endcomment -%}
{% for idx in product_indexes[1] %}
  {% assign product = reward_products[idx] %}
  <div class="gift-option">
    <img src="{{ product.featured_image | image_url: width: 100 }}" />
    <span>{{ product.title }}</span>
  </div>
{% endfor %}
```

### threshold_messages
**Type:** `list.single_line_text_field`

Custom display messages for each tier. Defaults to the discount title if not set.

```liquid
{% assign messages = discount.threshold_messages.value %}

<ul class="tier-list">
  {% for msg in messages %}
    <li>{{ msg }}</li>
  {% endfor %}
</ul>
```

---

## Advanced Fields

### test
**Type:** `boolean`

Whether this discount is in test mode. Test discounts only apply to customers tagged `test` and are excluded from `max_reward_percent` / `max_reward_cents` scalar metafields.

```liquid
{% unless discount.test %}
  <div class="badge">{{ discount.maximum_reward_value }}% OFF</div>
{% endunless %}
```

### config
**Type:** `json`

Complete discount configuration including tiers and rules. Structure varies by discount type.

```liquid
{% if discount.config %}
  {% assign config_data = discount.config.value %}
  {%- comment -%} Use with caution - structure varies {%- endcomment -%}
{% endif %}
```

---

## TypeScript Type

```typescript
interface DiscountSummary {
  // Core
  discount_title: string
  discount_type: 'PRODUCT_VOLUME' | 'ORDER_GOAL' | 'GWP' | 'BXGY' | 'BASIC' | 'FREE_SHIPPING' | 'SHIPPING' | 'CUSTOM' | 'UNKNOWN_APP'

  // Threshold
  threshold_type: 'QUANTITY' | 'AMOUNT' | 'NONE'
  minimum_threshold_value: number
  threshold_product_references: Array<{ id: string; title: string; handle: string }>
  threshold_collection_references: Array<{ id: string; title: string; handle: string }>

  // Reward
  reward_type: 'PERCENTAGE' | 'FIXED_AMOUNT' | 'FIXED_PRICE'
  minimum_reward_value: number
  maximum_reward_value: number
  reward_product_references: Array<{ id: string; title: string; handle: string }>
  reward_collection_references: Array<{ id: string; title: string; handle: string }>

  // Tier-Level Data
  thresholds: number[]
  reward_values: number[]
  reward_quantities: number[]
  reward_product_indexes: number[][]
  threshold_messages: string[]

  // Method & opt-in
  method: 'automatic' | 'code'
  code: string
  tags: string[]

  // Targeting
  included_customer_tags: string[]
  excluded_customer_tags: string[]
  included_markets: string[]
  excluded_markets: string[]
  currency: string | null
  allow_b2b: boolean | null
  only_b2b: boolean | null
  cart_attribute_key: string
  cart_attribute_value: string

  // Advanced
  test: boolean
  config: Record<string, any>
}
```

---

## Next Steps

    title="Code Examples"
    description="Practical implementations"
    href="/docs/live/examples/"
  />
    title="Introduction"
    description="Learn about Discount Kit Live"
    href="/docs/live/introduction/"
  />

---

# Settings

Source: https://discountkit.app/docs/live/settings/

LIVE sync settings let you control which metafields are written to your Shopify storefront. You can access them from the sync status popover on your Discount Kit dashboard.

![LIVE sync settings popover showing toggles for LIVE sync, Product metafields, Collection metafields, and Collection fan-out](/images/sync_settings.png)
*Sync settings in the dashboard popover*

## LIVE sync (top-level toggle)

Enables or disables all sync activity. When turned off, LIVE stops all Shopify writes — including product metafields, collection metafields, discount summary metaobjects, and the shop-level metafield.

Turning this off does not delete any metafields already written to Shopify — they simply stop being updated.

## Product metafields

When enabled, LIVE writes discount data to individual product metafields under the `app--9549316097--discount_kit` namespace. This includes:

- `discounts` — full JSON array of applicable discounts
- `max_reward_percent`, `max_reward_cents`, `max_reward_discount` — scalar values for the best universal discount

Disable this if you only need collection-level data or want to reduce write volume.

## Collection metafields

When enabled, LIVE writes discount data to collection metafields using the same namespace and keys as product metafields.

Disable this if your theme only uses product-level data.

## Collection fan-out

When enabled, LIVE resolves collection → product membership and writes product metafields for every product in a targeted collection. This means products inherit discounts from their parent collections automatically.

For example, a "Summer Sale" discount on the "T-Shirts" collection will be written to every product in that collection — no extra Liquid logic required.

:::note
Collection fan-out is limited to **8,000 unique products** across all collection-based discounts. Products beyond this limit still receive the correct discount at checkout but may not display badges on the storefront.
:::

## Important notes

- **Discount summaries sync with the top-level toggle** — metaobject summaries and the shop-level metafield update whenever LIVE sync is on, regardless of the product/collection sub-toggle settings.
- **Toggling a setting ON triggers an immediate sync** — changes are written within seconds.
- **Toggling everything OFF is safe** — metafields already in Shopify remain intact but stop being updated. You can re-enable at any time to resume.

---

# Storefront data

Source: https://discountkit.app/docs/live/storefront-data/

DiscountKit Live makes your discount data instantly accessible through
metafields using an app-specific namespace.

## Accessing discount data

Discount data is available through metafields on products, collections, and
the shop object using the namespace `app--9549316097--discount_kit` and key
`discounts`.

### Product-level discounts

Access all discounts that apply to a specific product, including discounts
inherited from collections the product belongs to:

```liquid
{% assign discounts = product.metafields.app--9549316097--discount_kit.discounts.value %}

{% if discounts.size > 0 %}
  {% for discount in discounts %}
    <div class="discount">
      <h3>{{ discount.discount_title }}</h3>
      <span>{{ discount.maximum_reward_value }}% OFF</span>
    </div>
  {% endfor %}
{% endif %}
```

### Collection-level discounts

Access discounts that target a collection directly. Note that these discounts
are also fanned out to every product in the collection, so you typically only
need collection metafields for collection page banners:

```liquid
{% assign discounts = collection.metafields.app--9549316097--discount_kit.discounts.value %}

{% if discounts.size > 0 %}
  <div class="collection-promo">
    <p>{{ discounts.first.discount_title }}</p>
  </div>
{% endif %}
```

### Shop-level discounts

Access all active discounts across your store:

```liquid
{% assign all_discounts = shop.metafields.app--9549316097--discount_kit.discounts.value %}

{% if all_discounts.size > 0 %}
  <div class="site-wide-promos">
    {% for discount in all_discounts %}
      <div>{{ discount.discount_title }}</div>
    {% endfor %}
  </div>
{% endif %}
```

## DiscountSummary object

Each discount in the array is a DiscountSummary metaobject with fields like:

- `discount_title` — Display name
- `discount_type` — Type (PRODUCT_VOLUME, ORDER_GOAL, GWP, etc.)
- `method` — `'automatic'` or `'code'`
- `code` — The discount code (empty for automatic discounts)
- `tags` — Tags applied to the discount in Shopify (includes `dk:live` plus any merchant tags)
- `reward_type` — PERCENTAGE, FIXED_AMOUNT, or FIXED_PRICE
- `maximum_reward_value` — Top tier discount value
- `included_markets` — Market handles where applicable
- `included_customer_tags` — Required customer tags
- `cart_attribute_key` — Cart attribute key required to apply

## Quick access: best discount value

For simple use cases where you just need to display the best discount value,
DiscountKit provides scalar metafields that are easier to work with than
parsing the full discount array.

:::note
Both `max_reward_percent` and `max_reward_cents` are always present, but only
one will have a non-zero value. Percentage discounts are preferred over
fixed-value discounts (fixed-amount or fixed-price). When a product or
collection has no active discounts, both values are `0`.
:::

:::caution
These scalar metafields only reflect **universal discounts** that apply to
all visitors. Test mode discounts, GWP discounts, customer-tagged discounts,
and market-specific discounts are excluded from scalar computation. They
still appear in the full `discounts` array.
:::

### Available metafields

| Metafield | Type | Description |
|-----------|------|-------------|
| `max_reward_percent` | `number_decimal` | Best percentage discount (e.g., `20` for 20% off) |
| `max_reward_cents` | `number_integer` | Best fixed-value reward in cents (discount amount or final price, e.g., `500` for $5 off or `1500` for a $15 final price) |
| `max_reward_discount` | `metaobject_reference` | Reference to the full DiscountSummary for additional details |

### Product example

```liquid
{% assign percent_off = product.metafields.app--9549316097--discount_kit.max_reward_percent.value %}
{% assign cents_off = product.metafields.app--9549316097--discount_kit.max_reward_cents.value %}

{% if percent_off %}
  <span class="badge">{{ percent_off | round }}% OFF</span>
{% elsif cents_off %}
  <span class="badge">{{ cents_off | divided_by: 100.0 | money }} OFF</span>
{% endif %}
```

### Collection example

```liquid
{% assign percent_off = collection.metafields.app--9549316097--discount_kit.max_reward_percent.value %}

{% if percent_off %}
  <div class="collection-badge">
    Save up to {{ percent_off | round }}%
  </div>
{% endif %}
```

### Accessing the full discount details

Use `max_reward_discount` to get additional info like the discount title or
message:

```liquid
{% assign best_discount = product.metafields.app--9549316097--discount_kit.max_reward_discount.value %}

{% if best_discount %}
  <div class="promo">
    <strong>{{ best_discount.discount_title }}</strong>
    <span>{{ best_discount.maximum_reward_value | round }}% OFF</span>
  </div>
{% endif %}
```

## Performance

Metafield access is instant with zero overhead:

- **No API calls** — data is already on the page
- **Server-rendered** — available during initial render
- **Always up-to-date** — synced automatically

## Next steps

Filtering, the complete DiscountSummary reference and copy-paste examples are
being migrated to these docs; see [Introduction](/docs/live/introduction/)
for how Live syncs in the meantime.

---

# POS specific discounts

Source: https://discountkit.app/docs/pos/overview/

![POS only discount image](/images/pos-only-discount.png)

Our Retail Location Discount feature empowers you to offer exclusive discounts directly at your point of sale. This innovative tool allows you to customize promotions for specific store locations, providing a personalized shopping experience for your local customers.

Leverage this feature to create discounts tailored to each retail spot. Whether you're running a sale in one city or offering special deals in another, you can easily manage these promotions through Discount Kit.

When setting up a discount, simply navigate to the 'Eligibility' options in your admin panel. Here, you can specify which store locations will offer the discount.<br /><br />

Selecting `is none`, of `All locations` will result in the discount applying to all non-POS sales channels. Selecting `is some`, of `All locations` will result in the discount being a POS-only discount, that won't apply on any other sale channel.

---

# Sidekick

Source: https://discountkit.app/docs/sidekick/

[Sidekick](https://www.shopify.com/sidekick) is Shopify's built-in AI
assistant. Discount Kit plugs directly into Sidekick, so you can build, find,
and explain your discounts in plain language — without clicking through the
editor yourself.

Ask Sidekick for a discount the way you'd describe it to a teammate, and it
fills out the Discount Kit builder for you. You always review the result and
press **Save** before anything goes live.

## What you can do

    Describe a promotion and Sidekick opens the right Discount Kit builder and
    fills in the settings.
    Ask Sidekick to list or search your existing Discount Kit discounts.
    Get a plain-language breakdown of what a discount does and when it applies.
    Open an existing discount and ask Sidekick to adjust its settings.

Sidekick can work with every Discount Kit discount type:

- **Custom** — buckets, conditions, targets, BOGO, and bundle pricing
- **Product volume** — quantity-based tiers on products
- **Order goal** — spend or quantity thresholds across the order
- **Gift with purchase** — free or discounted gifts at a threshold
- **Shipping** — discounted or free shipping with optional conditions

## How to use it

1. **Open Sidekick**

   Click the Sidekick icon in your Shopify admin to open the chat.

2. **Describe what you want**

   Tell Sidekick the discount you'd like to create, find, or change. The more
   specific you are about the products, amount, and conditions, the better the
   result.

3. **Review the proposal**

   Sidekick opens the Discount Kit builder and fills in your settings. Check
   every field — the discount amount, conditions, and which products it
   targets.

4. **Save**

   When it looks right, press **Save**. Nothing is live until you do. If
   something's off, ask Sidekick to adjust it or edit the form yourself before
   saving.

## Example prompts

<details>
<summary>Create a discount</summary>

- "Create an order discount that takes 10% off when the cart total is over
  $100, and 20% off over $200."
- "Set up a Buy 2 Get 1 free on the Hats collection."
- "Make a volume discount: 5% off 3 items, 10% off 5 items."
- "Add a free gift when a customer spends more than $75."
- "Give free shipping on orders over $50."

</details>

<details>
<summary>Find a discount</summary>

- "Show me my active Discount Kit discounts."
- "Which discounts apply to the Summer collection?"
- "List my order goal discounts."

</details>

<details>
<summary>Explain a discount</summary>

- "Explain my 'Spring Sale' discount."
- "When does my free shipping discount apply?"

</details>

<details>
<summary>Edit a discount</summary>

- "Open my 'BFCM' discount and change the threshold to $150."
- "Add an exclusion for the Clearance collection to my order discount."

</details>

## Tips for better results

- **Be specific about amounts and conditions.** "20% off orders over $200" is
  clearer than "a bigger discount for big orders."
- **Name products and collections.** Mention the exact collection or product so
  Sidekick targets the right items.
- **Build one discount at a time.** Keep each request focused, then refine it in
  follow-up messages.
- **Always review before saving.** Sidekick is a head start, not a replacement
  for a final check — confirm the amount, conditions, and targeted products.

:::note
Sidekick proposes settings in the Discount Kit builder, but it never saves or
activates a discount for you. You stay in control: review the form and press
**Save** when you're ready.
:::

:::tip
Want to try a discount before it reaches real customers? Combine Sidekick with
[Test mode](/docs/test-mode/) — create the discount with Sidekick, then enable test
mode so only customers tagged `test` can see it.
:::

## Related

---

# Test mode

Source: https://discountkit.app/docs/test-mode/

Test mode lets you try out Discount Kit's discounts on your store before subscribing. Create any discount type, enable test mode, and only customers tagged `test` will see and receive the discount. Your real customers are never affected.

## How it works

1. **Create a discount** — choose any discount type and configure it as you normally would
2. **Enable test mode** — toggle test mode on in the discount settings
3. **Tag a customer** — add the `test` tag to a customer account in your Shopify admin
4. **Log in and test** — log in to your storefront as that customer and verify the discount applies

:::note
Test mode discounts require the customer to be **logged in** with the `test` tag. Customers without the tag, and guests who are not logged in, will not see or receive the discount.
:::

## No subscription required

Test mode is available on all plans, including before you subscribe. This means you can fully verify that a discount works for your use case before committing to a plan.

Once you're happy with the results, subscribe to a plan and then disable test mode to make the discount live for all eligible customers.

## Tagging a customer for testing

In your Shopify admin:

1. Go to **Customers**
2. Select the customer you want to use for testing
3. In the **Tags** section, add the tag `test`
4. Save the customer

## Storefront visibility

If you're using [Discount Kit Live](/docs/live/introduction/) to display discounts on your storefront, test mode discounts are automatically excluded from the `max_reward_percent` and `max_reward_cents` scalar metafields. This means your storefront badges and banners won't show test discounts to regular customers.

If you're working with the full `discounts` array, you can filter test mode discounts using the `test` field. See [filtering test mode discounts](/docs/live/filtering-discounts/#filtering-test-mode-discounts) for details.