# Product updates
Source: https://discountkit.app/changelog

Track updates, improvements, and bug fixes to Discount Kit

All notable changes to Discount Kit will be documented on this page.

<Update label="June 2026">
  * **Customer context**: Every discount type now has an **Eligibility** card,
    powered by Shopify's native discount context. Limit a discount to specific
    **customer segments** or **markets** (the two are mutually exclusive). The
    Eligibility card targets the full range of your Shopify markets, while the
    legacy **Market eligibility** option in the sidebar continues to target
    regional markets only. Note: discounts limited to segments or markets can't
    operate with Discount Kit Live storefront components. See
    [Customer context](/discounts/common-settings#customer-context).
  * **Sidekick AI assistant**: Discount Kit now works with
    [Sidekick](/sidekick), Shopify's built-in AI assistant. Describe a discount
    in plain language and Sidekick fills in the Discount Kit builder for you —
    across Custom, Product Volume, Order Goal, Gift with Purchase, and Shipping
    discounts. Sidekick can also find and explain your existing discounts. You
    always review and Save before anything goes live. See [Sidekick](/sidekick).
</Update>

<Update label="May 2026">
  * **Custom Discount — Unique Groups condition**: New cart condition that
    fires when the cart contains items from at least N of a selected list of
    Cart Groups. Useful for **Routine Builder**-style offers ("10% off when
    you buy from 2 of these 4 steps, 15% for 3 steps, 20% for all 4") and
    any promotion that rewards spanning categories rather than buying a
    certain quantity of one thing. Requires at least 2 Cart Groups and a
    minimum count of 2 or higher. See [Unique Groups condition](/discounts/custom#unique-groups-condition).
  * **Discount Kit Live — opt-in via tags**: Discount Kit Live is now
    opt-in. Tag a discount `dk:live` to surface it on your storefront; remove
    the tag to hide it. Works for both **automatic** and **code-based**
    discounts. Existing shops were auto-migrated, so nothing dropped on
    rollout. The `discount_summary` metaobject gains `method`
    (`automatic`/`code`), `code`, and `tags` fields for storefront use. See
    [Discount Kit Live introduction](/live/introduction).
  * **Tags**: Label any discount with up to 5 tags (`SEASONAL`, `LOYALTY`,
    `BFCM`, …). Autocomplete suggests tags you've used elsewhere. Filter or
    bulk-action discounts by tag from Shopify's native discounts list.
  * **Cart-line stacking** (Shopify Plus): Two product discounts can now apply
    to the same cart line when they share a tag in each other's cart-line
    combination list. Set this up in the Combinations card under
    Product discounts. See [Stacking discounts](/discounts/stacking) for the
    full pattern.
  * Admin app upgraded to Shopify Admin API `2026-04`.
</Update>

<Update label="April 2026">
  * **Built for Shopify**: Discount Kit retained its Built for Shopify
    status — Shopify's recognition of continued performance, quality, and
    merchant-experience standards
  * **Order Discount**: Added an "Exclude products with compare at prices" toggle
  * **Discount metafields**: Product-discount metafields are now
    `admin_filterable` and `analytics_queryable` — surface Discount Kit
    values in Shopify admin product filters and Shopify analytics reports
  * **Discount Functions**: All Discount Kit functions updated to Shopify
    Admin API `2026-04`
</Update>

<Update label="March 2026">
  * **Custom Discount**: Metafield Discount now supports `discount_fixed_price` — set
    items to a specific price (e.g. `2500` for \$25.00) instead of only discounting
    by a fixed amount or percentage. The metafield schema also now allows
    additional custom properties (e.g. `discount_badge`) for use by theme code
  * **Custom Discount**: Bundle pricing — create "3 for \$25" style offers with
    repeating targets and fixed prices, no qualifiers needed
  * **Custom Discount**: Consume mode — prevent discounted items from being
    targeted by subsequent rules within the same discount. Useful for prioritizing
    offers and preventing double-discounting
  * **Custom Discount**: Improved Buy X Get Y — qualifiers and targets now share
    a unified layout with smarter handling when both reference the same cart group
  * **Cart attribute filter**: Gate any discount behind a cart attribute. Require
    a specific key to be present, or require an exact key + value match. Works
    across all discount types (Custom, Volume, Order Goal, GWP, Shipping)
  * **Discount Kit Live**: Collection fan-out — discounts targeting collections
    are now automatically resolved to individual products, so product metafields
    include both direct and collection-inherited discounts. No extra Liquid logic
    needed for product badges.
  * **Discount Kit Live**: Write-skip fingerprinting — unchanged metafields are
    no longer rewritten on each sync, reducing API usage and improving sync speed
  * **Discount Kit Live**: Parallel collection resolution (3x faster) and
    real-time sync progress visible in the dashboard
</Update>

<Update label="February 2026">
  * **Discount Kit Live**: Scalar metafields (`max_reward_percent`,
    `max_reward_cents`) now only reflect discounts visible to all visitors. New
    `test` field on DiscountSummary for easy Liquid filtering
  * **Custom Discount**: Nested and parent line targeting — target specific line
    items within bundles or target the parent line of a bundle for more precise
    discount control
  * **B2B eligibility**: New "B2B only" option to restrict discounts exclusively
    to B2B company buyers, in addition to the existing "All customers" mode
</Update>

<Update label="January 2026">
  * **Custom Discount**: Per-proposal eligibility conditions for more granular
    discount control - **Gift with Purchase**: Consolidated storefront settings
    into a single app embed - **Discount Kit Live**: New tier-level fields
    (`thresholds`, `reward_values`, `reward_quantities`, `reward_product_indexes`,
    `threshold_messages`) for building dynamic storefront UIs like progress bars
    and gift selectors
</Update>

<Update label="December 2025">
  * **Discount Kit Live**: New quick-access metafields (`max_reward_percent`,
    `max_reward_cents`, `max_reward_discount`) for simplified storefront badge
    displays
</Update>

<Update label="November 2025">
  * Order discount now supports excluded collections. Excluded items don't count
    towards thresholds and don't receive the discount - Gift with Purchase: Added
    option to prevent re-adding manually removed gifts, plus performance and
    stability improvements
</Update>

<Update label="October 2025">
  * Discount Kit Live. Create bespoke storefront experiences with instantly
    available discount data! - Gift with Purchase, Product Volume, and Order Goal
    migrated to Polaris Web Components
</Update>

<Update label="September 2025">
  * Expanded support to cover 24/7, 365. - Admin migration to Polaris Web
    Components - Markets/locations improvements (limit 250, selector updates)
</Update>

<Update label="August 2025">
  * Migrated to Remix Router v7 - Public status page at
    [status.discountkit.app](https://status.discountkit.app) - Added our
    Enterprise plan, with lots of features for our larger customers - Target a
    specific currency in a discount proposal - Create fixed price proposals
    without recurring rules - Target the cheapest or most expensive product
    targets - Target 'existing' customers across all discounts
</Update>

<Update label="July 2025">
  * New Tiered Pricing function and UI extension - Shipping improvements:
    delivery option cost to input, new operators added
</Update>

<Update label="June 2025">
  * Retail support across our discounts, including retail only, specific
    location, or any mix of online and retail
</Update>

<Update label="May 2025">
  * Performance improvements allowing for significantly larger input to
    functions - Multi effect (also known as multi class) support added to the
    Custom discount. Order and shipping in one code? You got it! - New
    'conditions' UI for the Custom discount, allowing more powerful, and more
    readable discount configurations - 'Test mode', which lets you take Discount
    Kit for a spin without needing a subscription - Support for 2048 variants
</Update>

<Update label="March 2025">
  * More options to include or exclude markets or customer tags - Recurring
    payments support for an arbitrary number of cycles
</Update>

<Update label="February 2025">
  * Function performance improvements to cart iteration
</Update>

<Update label="January 2025">
  * Performance improvements. An average of almost 60% gains across all of our
    discount functions - Custom Discount product‑level metafield support - "Apply
    to compare‑at price" option - Updates to our Gift selector component
</Update>

<Update label="December 2024">
  * Subscription vs one‑time handling - More options added to the shipping
    discount conditional operators
</Update>


# App blocks vs. Web Components
Source: https://discountkit.app/components/app-blocks-vs-web-components

The two ways to place a Live Component, and when to use each

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](/components/overview#enable-the-‘discount-kit-live’-app-embed).
</Note>

## 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 theme={null}
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 theme={null}
<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 theme={null}
<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?

<CardGroup>
  <Card title="Reach for an app block" icon="puzzle-piece">
    The merchant should configure it without code · you need it in a **product card** ·
    you want styling managed from the theme editor.
  </Card>

  <Card title="Reach for a web component" icon="code">
    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.
  </Card>
</CardGroup>

## Next steps

<CardGroup>
  <Card title="Overview" icon="circle-info" href="/components/overview">
    Enabling the runtime and theming with `--dkl-*` tokens.
  </Card>

  <Card title="Discount Price" icon="tag" href="/components/price/overview">
    See both placement paths on a real component.
  </Card>
</CardGroup>


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

Add and configure the DK: Discount Badge block from the theme editor

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](/live/reference) itself, and
server-renders the correct badge.

<Info>
  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.
</Info>

## Add the block

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Settings

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

### Content

<ParamField type="select">
  Which amount to show — **Percentage** (e.g. 20%), **Fixed amount** (e.g. \$5.00), or
  **Highest amount** (whichever saves more).
</ParamField>

<ParamField type="text">
  Label template. Use `[amount]` for the discount value.
</ParamField>

### Style

<ParamField type="range">
  Space above the badge, 0–80px.
</ParamField>

<ParamField type="range">
  Space below the badge, 0–80px.
</ParamField>

<ParamField type="color">
  Badge background. Defaults to the accent brand colour.
</ParamField>

<ParamField type="color">
  Badge text. Defaults to white.
</ParamField>

<ParamField type="range">
  Badge corners, 0–24px.
</ParamField>

<ParamField type="range">
  Vertical padding, 0–32px.
</ParamField>

<ParamField type="range">
  Horizontal padding, 0–48px.
</ParamField>

<ParamField type="range">
  Badge text size, 8–48px.
</ParamField>

<ParamField type="range">
  Badge text size on mobile, 8–48px.
</ParamField>

<ParamField type="range">
  Badge text weight, 100–900. Font weights may be limited to your theme's installed font files.
</ParamField>

<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.
</Note>

## Next steps

<CardGroup>
  <Card title="Web Component" icon="code" href="/components/discount-badge/web-component">
    The same component placed by hand, configured with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/discount-badge/styling-and-data">
    The tokens and attributes behind these settings.
  </Card>
</CardGroup>


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

The lifecycle events <dkl-discount-badge> emits

`<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.

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

<ParamField type="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.
</ParamField>

```js theme={null}
// 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](/components/discount-badge/web-component#reacting-to-changes).
</Tip>

## Next steps

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/discount-badge/web-component">
    Drop-in usage and the `MutationObserver` example.
  </Card>

  <Card title="Discount Badge overview" icon="circle-info" href="/components/discount-badge/overview">
    What the component does and how it reads the discount.
  </Card>
</CardGroup>


# Discount Badge
Source: https://discountkit.app/components/discount-badge/overview

A theme-agnostic max-discount badge for products and product cards

<Frame>
  <img alt="DKL Discount Badge component" />
</Frame>

`<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](/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

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/discount-badge/app-block">
    Add **DK: Discount Badge** in the theme editor and configure it with settings — no code.
    The only way to render in collection product cards.
  </Card>

  <Card title="Web Components" icon="code" href="/components/discount-badge/web-component">
    Drop `<dkl-discount-badge>` straight into your theme's Liquid and configure with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/discount-badge/styling-and-data">
    The `data-*` attributes and `--dkl-badge-*` styling tokens shared by both.
  </Card>

  <Card title="Events" icon="bell" href="/components/discount-badge/events">
    The mount / unmount lifecycle events each instance emits.
  </Card>
</CardGroup>

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

<Info>
  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](/components/discount-badge/events).
</Info>

## 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/components/discount-badge/styling-and-data

The data-* attributes and CSS styling tokens for <dkl-discount-badge>

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](/components/discount-badge/app-block) settings map onto these; on a [web component](/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](/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](/components/discount-badge/web-component) only. To change block behaviour, use its [settings](/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 { … }`).
</Note>

<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.
</Tip>

## Data attributes

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

<ParamField type="&#x22;percentage&#x22; | &#x22;fixed&#x22; | &#x22;highest&#x22;">
  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.
</ParamField>

<ParamField type="number (decimal percent)">
  The percentage amount (rounded for display).
</ParamField>

<ParamField type="int (cents)">
  The fixed amount (money-formatted).
</ParamField>

<ParamField type="int (cents)">
  The variant price; drives the `highest` comparison (recomputed on variant change).
</ParamField>

<ParamField type="string">
  Money format for the `fixed` amount.
</ParamField>

<ParamField type="string">
  Label template; `[amount]` is replaced with the formatted amount.
</ParamField>

<Info>
  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.
</Info>

## CSS styling tokens

<Frame>
  <img alt="Image highlighting the CSS styling tokens for the DKL Discount Badge component" />
</Frame>

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.

<ParamField>
  Badge background.
</ParamField>

<ParamField>
  Badge text.
</ParamField>

<ParamField>
  Badge corners.
</ParamField>

<ParamField>
  Vertical padding.
</ParamField>

<ParamField>
  Horizontal padding.
</ParamField>

<ParamField>
  Badge text size.
</ParamField>

<ParamField>
  Badge text weight.
</ParamField>

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 Restyle a single badge inline theme={null}
<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 Style the host via :root tokens theme={null}
:root {
  --dkl-badge-background: #111;
  --dkl-badge-color: #fff;
  --dkl-badge-radius: 999px;
}
```

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

## Next steps

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/discount-badge/app-block">
    Configure these via theme-editor settings.
  </Card>

  <Card title="Web Components" icon="code" href="/components/discount-badge/web-component">
    Set these directly on the tag.
  </Card>
</CardGroup>


# Web Component
Source: https://discountkit.app/components/discount-badge/web-component

Drop <dkl-discount-badge> into your theme markup and configure it with data-* attributes

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 theme={null}
<dkl-discount-badge></dkl-discount-badge>
```

<Warning>
  #### 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](/components/discount-badge/app-block) instead, which renders inline per card
  (resolving each card's own product). See
  [App blocks vs. Web Components](/components/app-blocks-vs-web-components).
</Warning>

## 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](/components/discount-badge/styling-and-data).

```html Whichever discount saves more theme={null}
<dkl-discount-badge data-discount-type="highest"></dkl-discount-badge>
```

```html Override attributes + tokens theme={null}
<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 React to badge updates theme={null}
// <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

<CardGroup>
  <Card title="Styling & Data Attributes" icon="palette" href="/components/discount-badge/styling-and-data">
    Every `data-*` attribute and `--dkl-badge-*` token.
  </Card>

  <Card title="App block" icon="puzzle-piece" href="/components/discount-badge/app-block">
    The no-code, theme-editor placement.
  </Card>
</CardGroup>


# Styling
Source: https://discountkit.app/components/global-styling

Theme the Live Components with global brand tokens and per-component tokens

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 theme={null}
/* 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.

<ParamField>
  Component font family. Custom font families must be installed on the theme.
</ParamField>

<ParamField>
  Default text colour.
</ParamField>

<ParamField>
  Accent / selected state.
</ParamField>

<ParamField>
  Success / savings colour.
</ParamField>

<ParamField>
  Border colour.
</ParamField>

<ParamField>
  Corner radius for all components.
</ParamField>

## 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:

<CardGroup>
  <Card title="Discount Price" icon="tag" href="/components/price/styling-and-data">
    `--dkl-price-*` tokens and `::part()` targets.
  </Card>

  <Card title="Volume Picker" icon="layer-group" href="/components/volume-picker/styling-and-data">
    `--dkl-vp-*` tokens, CSS parts, and light-DOM classes.
  </Card>

  <Card title="Discount Badge" icon="badge-percent" href="/components/discount-badge/styling-and-data">
    `--dkl-badge-*` tokens (light-DOM, host-only).
  </Card>

  <Card title="Order Goal" icon="bullseye-arrow" href="/components/order-goal/styling-and-data">
    `--dkl-og-*` tokens and light-DOM classes.
  </Card>
</CardGroup>

## App block vs. web component

<Info>
  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.
</Info>

## 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.

<Info>
  **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.
</Info>


# Live Data & Live Components
Source: https://discountkit.app/components/live-data-live-components

How the Discount Kit Live data differs from the Discount Kit Live components, and how to use them together in your storefront

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](/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](/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](/live/introduction) for how syncing works.
</Note>

## 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](/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?

<CardGroup>
  <Card title="Reach for Live Components" icon="puzzle-piece" href="/components/overview">
    You want a price, volume picker, badge, or order-goal bar with minimal code · the merchant
    should configure it in the theme editor · you want it themed with tokens.
  </Card>

  <Card title="Reach for Live Data" icon="code" href="/live/storefront-data">
    You need a fully custom layout or logic a component doesn't provide · you're comfortable
    reading metafields and writing the Liquid yourself.
  </Card>
</CardGroup>

<Note>
  The Live Components are currently in **beta**. The Live Data API is stable and unaffected.
</Note>


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

Add and configure the DK: Order Goal block from the theme editor

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Settings

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

### Discount & layout

<ParamField type="metaobject">
  Show only this order goal discount. Leave empty to show the first one.
</ParamField>

<ParamField type="select">
  **Horizontal**, or **Stacked** (markers in a column, progress bar rotated).
</ParamField>

### Content

<ParamField type="text">
  Shown until every tier is met. Use `[amount]` for the amount to the next tier and
  `[discount]` for its discount.
</ParamField>

<ParamField type="text">
  Heading shown once every tier is met.
</ParamField>

<ParamField type="text">
  Body shown once every tier is met.
</ParamField>

<ParamField type="text">
  Use `[discount]` for the tier's discount.
</ParamField>

<ParamField type="text">
  Use `[amount]` for the tier's minimum spend.
</ParamField>

### Spacing & sizing

<ParamField type="range">
  Space above the widget, 0–80px.
</ParamField>

<ParamField type="range">
  Space below the widget, 0–80px.
</ParamField>

<ParamField type="range">
  Inner padding of the card, 0–48px.
</ParamField>

<ParamField type="select">
  **Inherit**, or **Custom**. The two font-size settings below apply only when set to Custom.
</ParamField>

<ParamField type="range">
  Desktop font size, 10–32px. Custom only.
</ParamField>

<ParamField type="range">
  Mobile font size, 8–28px. Custom only.
</ParamField>

<ParamField type="range">
  Card corners, 0–24px.
</ParamField>

### Colors

<ParamField type="color">
  The progress fill.
</ParamField>

<ParamField type="color">
  The unfilled progress track behind the fill.
</ParamField>

<ParamField type="color">
  Card background.
</ParamField>

<ParamField type="color">
  The headline / progress message.
</ParamField>

<ParamField type="color">
  The per-tier "Save \[discount]" line.
</ParamField>

<ParamField type="color">
  The per-tier "when you spend \[amount]+" line.
</ParamField>

<ParamField type="color">
  Marker background for tiers not yet met.
</ParamField>

<ParamField type="color">
  Marker background for met tiers.
</ParamField>

### Icons

<ParamField type="image">
  Swaps the marker glyph for a custom image on percentage-discount tiers.
</ParamField>

<ParamField type="image">
  Swaps the marker glyph for a custom image on fixed-amount tiers.
</ParamField>

<ParamField type="image">
  Swaps the marker glyph for a custom image once a tier is met.
</ParamField>

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

## Next steps

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/order-goal/web-component">
    The same component placed by hand, configured with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/order-goal/styling-and-data">
    The tokens, classes, and attributes behind these settings.
  </Card>
</CardGroup>


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

The event <dkl-order-goal> emits

`<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](/components/order-goal/web-component#reacting-to-changes)
and the examples on the [web component](/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.
</Note>

<ParamField type="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 theme={null}
  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`.
</ParamField>

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

```js theme={null}
// 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).

<ParamField type="CustomEvent">
  Fired once the controller has attached its behaviour to the (already server-rendered)
  element, after the baseline tier is established. `resource`: `{ widgetType, widgetId }`.
</ParamField>

<ParamField type="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.
</ParamField>

```js theme={null}
// 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

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/order-goal/web-component">
    Listener and payload examples for reacting to tier changes.
  </Card>

  <Card title="Order Goal overview" icon="circle-info" href="/components/order-goal/overview">
    What the component does, and how it reads the cart total.
  </Card>
</CardGroup>


# Order Goal
Source: https://discountkit.app/components/order-goal/overview

Cart progress bar toward an order-goal discount's spend tiers

<Tabs>
  <Tab title="Layout: Stacked">
    <Frame>
      <img alt="Image highlighting the DKL Order Goal component - layout: stacked" />
    </Frame>
  </Tab>

  <Tab title="Layout: Horizontal">
    <Frame>
      <img alt="Image highlighting the DKL Order Goal component - layout: horizontal" />
    </Frame>
  </Tab>
</Tabs>

`<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](/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.

<Info>
  **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.
</Info>

## On this component

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/order-goal/app-block">
    Add **DK: Order Goal** in the theme editor and configure it with settings — no code.
  </Card>

  <Card title="Web Components" icon="code" href="/components/order-goal/web-component">
    Drop `<dkl-order-goal>` straight into your theme's Liquid and configure with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/order-goal/styling-and-data">
    The `data-*` attributes, `--dkl-og-*` styling tokens, and Light-DOM classes shared by both.
  </Card>

  <Card title="Events" icon="bell" href="/components/order-goal/events">
    The tier-change event `<dkl-order-goal>` emits.
  </Card>
</CardGroup>

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

## 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/components/order-goal/styling-and-data

The data-* attributes, CSS styling tokens, and Light-DOM classes for <dkl-order-goal>

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](/components/order-goal/app-block) settings map onto these; on a [custom
element](/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](/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](/components/order-goal/web-component) only. To change block
  behaviour, use its [settings](/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.
</Note>

<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.
</Tip>

## Data attributes

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

<ParamField type="metaobject handle">
  Pick a specific order-goal discount's carrier. The `discount-` prefix is optional; place one
  tag per discount to show several.
</ParamField>

<ParamField type="int">
  The baseline cart total.
</ParamField>

<ParamField type="string">
  Money format for JS-rendered amounts.
</ParamField>

<ParamField type="string">
  The spend-more message. `[amount]` and `[discount]` are replaced at runtime.
</ParamField>

<ParamField type="string">
  Heading shown once every tier is met.
</ParamField>

<ParamField type="string">
  Content shown once every tier is met.
</ParamField>

<ParamField type="string">
  Per-tier label; `[discount]` is the placeholder.
</ParamField>

<ParamField type="string">
  Per-tier spend line; `[amount]` is the placeholder.
</ParamField>

<ParamField type="&#x22;horizontal&#x22; | &#x22;stacked&#x22;">
  Layout variant. `stacked` arranges markers in a column with the progress bar rotated.
</ParamField>

## CSS styling tokens

<Tabs>
  <Tab title="Layout: Stacked">
    <Frame>
      <img alt="Image highlighting the CSS styling tokens for the DKL Order Goal component - layout: stacked" />
    </Frame>
  </Tab>

  <Tab title="Layout: Horizontal">
    <Frame>
      <img alt="Image highlighting the CSS styling tokens for the DKL Order Goal component - layout: horizontal" />
    </Frame>
  </Tab>
</Tabs>

`<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).

<ParamField>
  Space above the widget (block **Margin top**).
</ParamField>

<ParamField>
  Space below the widget (block **Margin bottom**).
</ParamField>

<ParamField>
  Card background (block **Background color**).
</ParamField>

<ParamField>
  Card padding (block **Padding**).
</ParamField>

<ParamField>
  Card corners (block **Border radius**).
</ParamField>

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

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

<ParamField>
  Card text colour (block **Text color**).
</ParamField>

<ParamField>
  The "Save \[discount]" tier label (block **Tier label color**).
</ParamField>

<ParamField>
  The "when you spend \[amount]+" tier line (block **Tier spend label color**).
</ParamField>

<ParamField>
  Progress track (unfilled bar) colour (block **Track color**).
</ParamField>

<ParamField>
  Progress fill colour (block **Progress bar color**).
</ParamField>

<ParamField>
  Tier marker size.
</ParamField>

<ParamField>
  Inactive marker border colour.
</ParamField>

<ParamField>
  Inactive marker fill (block **Icon background (not met)**).
</ParamField>

<ParamField>
  Active (met) marker fill (block **Icon background (met)**).
</ParamField>

<ParamField>
  Active marker check-icon colour.
</ParamField>

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

<Warning>
  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.
</Warning>

## Light-DOM classes

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

<ParamField type="host">
  The card (host element).
</ParamField>

<ParamField type="class">
  The headline / progress message.
</ParamField>

<ParamField type="class">
  The progress bar (with `.dkl-order-goal__progress-track`; the fill is the track's `::before`).
</ParamField>

<ParamField type="class">
  The tier row/column.
</ParamField>

<ParamField type="class">
  The wrapper for each tier.
</ParamField>

<ParamField type="class">
  The marker dot (met: `.dkl-order-goal__tier-marker--active`; the icon glyph is its `::before`).
</ParamField>

<ParamField type="class">
  The wrapper for the tier label.
</ParamField>

<ParamField type="class">
  The "Save \[discount]" text in the tier label.
</ParamField>

<ParamField type="class">
  The "when you spend \[amount]+" text in the tier label.
</ParamField>

## Examples

```css Restyle the progress fill and markers theme={null}
: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 Custom messaging theme={null}
<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

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/order-goal/app-block">
    Configure these via theme-editor settings.
  </Card>

  <Card title="Web Components" icon="code" href="/components/order-goal/web-component">
    Set these directly on the tag.
  </Card>
</CardGroup>


# Web Component
Source: https://discountkit.app/components/order-goal/web-component

Drop <dkl-order-goal> into your theme markup and configure it with data-* attributes

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 theme={null}
<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 theme={null}
<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](/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](/components/order-goal/styling-and-data).

```html Override attributes + tokens theme={null}
<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 Stacked layout theme={null}
<dkl-order-goal data-layout="stacked"></dkl-order-goal>
```

```js Listen for tier changes theme={null}
// 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 Example event payload theme={null}
// 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

<CardGroup>
  <Card title="Styling & Data Attributes" icon="palette" href="/components/order-goal/styling-and-data">
    Every `data-*` attribute, `--dkl-og-*` token, and Light-DOM class.
  </Card>

  <Card title="App block" icon="puzzle-piece" href="/components/order-goal/app-block">
    The no-code, theme-editor placement.
  </Card>
</CardGroup>


# Overview
Source: https://discountkit.app/components/overview

Drop-in storefront web components for Discount Kit Live

Live Components are a set of `<dkl-*>` web components that render discount UI
directly in your storefront — a [volume picker](/components/volume-picker/overview), a
[discount-aware price](/components/price/overview), a [max-discount badge](/components/discount-badge/overview),
and an [order-goal progress bar](/components/order-goal/overview). They read the same
[Discount Kit Live data](/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](/live/introduction) for how syncing works.
</Note>

## Enable the 'Discount Kit Live' app embed

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

<Steps>
  <Step title="Open the theme editor">
    In the Shopify admin, go to **Online Store → Themes** and click **Customize**.
  </Step>

  <Step title="Find the app embeds">
    Open **App embeds** in the left sidebar.
  </Step>

  <Step title="Enable Discount Kit Live">
    Toggle **Discount Kit Live** on, then click **Save**.
  </Step>
</Steps>

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.

<Info>
  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](/components/global-styling).
</Info>

## 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.

<CardGroup>
  <Card title="App blocks" icon="puzzle-piece">
    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.
  </Card>

  <Card title="Web Components" icon="code">
    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.
  </Card>
</CardGroup>

See [App blocks vs. Web Components](/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](/components/price/overview) re-prices on a variant change
  * the [volume picker](/components/volume-picker/overview) re-calculates the selected tier on variant change
  * the [badge](/components/discount-badge/overview) re-picks the best discount
* **`shopify:cart:lines-update`** drives cart-level updates:
  * the [order goal](/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.
</Note>

## 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](/components/global-styling) for the full token reference, how to apply them, and how
to target structural elements.

## The components

<CardGroup>
  <Card title="Discount Price" icon="tag" href="/components/price/overview">
    `<dkl-price>` — a theme-agnostic price that shows the discounted amount and a
    struck-through original as tiers and variants change.
  </Card>

  <Card title="Volume Picker" icon="layer-group" href="/components/volume-picker/overview">
    `<dkl-volume-picker-radio-groups>` — a PDP selector for volume/tiered discounts, one
    radio card per tier.
  </Card>

  <Card title="Discount Badge" icon="badge-percent" href="/components/discount-badge/overview">
    `<dkl-discount-badge>` — a "Save up to 20%" / "Save up to \$5.00" badge for products
    and product cards.
  </Card>

  <Card title="Order Goal" icon="bullseye-arrow" href="/components/order-goal/overview">
    `<dkl-order-goal>` — a cart progress bar toward an order-goal discount's spend tiers.
  </Card>
</CardGroup>


# App block
Source: https://discountkit.app/components/price/app-block

Add and configure the DK: Price block from the theme editor

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Edit a product template">Switch the top template selector to a **Product** template.</Step>

  <Step title="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.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

<Tip>
  #### Pairing with the volume picker

  Leave the [volume picker's](/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.
</Tip>

## Settings

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

### Savings badge

<ParamField type="checkbox">
  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.
</ParamField>

<ParamField type="select">
  How the saving displays — **Percentage** (e.g. 20%) or **Amount** (e.g. \$5.00).
</ParamField>

<ParamField type="text">
  The savings badge's leading label, e.g. "**Save** 15%".
</ParamField>

<ParamField type="text">
  Shown between the sale and tier savings, e.g. "Save 10% **+ an extra** 15%".
</ParamField>

<ParamField type="color">
  Background colour for the savings badge.
</ParamField>

<ParamField type="color">
  Text colour within the savings badge.
</ParamField>

<ParamField type="range">
  Corner radius for the savings badge, 0–24px.
</ParamField>

### Spacing

<ParamField type="range">
  Space above the widget, 0–80px.
</ParamField>

<ParamField type="range">
  Space below the widget, 0–80px.
</ParamField>

### Colors

<ParamField type="color">
  The main price. Defaults to the theme's inherited text colour.
</ParamField>

<ParamField type="color">
  Shown when a volume tier is selected. Falls back to the **Price color**.
</ParamField>

<ParamField type="color">
  The compared-to (struck-through) price.
</ParamField>

<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.
</Note>

## Next steps

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/price/web-component">
    The same component placed by hand, configured with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/price/styling-and-data">
    The tokens, parts, and attributes behind these settings.
  </Card>
</CardGroup>


# Events
Source: https://discountkit.app/components/price/events

The events <dkl-price> listens for and emits

`<dkl-price>` is event-driven. It has **no direct reference** to the
[volume picker](/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

<ParamField type="CustomEvent">
  Emitted by the [volume picker](/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).
</ParamField>

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).
</Note>

### Price change

<ParamField type="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 theme={null}
  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 }
  ```
</ParamField>

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

```js theme={null}
// 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.

<ParamField type="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.
</ParamField>

<ParamField type="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.
</ParamField>

```js theme={null}
// 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

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/price/web-component">
    Listener and `MutationObserver` examples for reacting to changes.
  </Card>

  <Card title="Volume Picker" icon="layer-group" href="/components/volume-picker/overview">
    The component that emits the tier-change event.
  </Card>
</CardGroup>


# Discount Price
Source: https://discountkit.app/components/price/overview

Theme-agnostic price display that reacts to volume tiers and variant changes

<Frame>
  <img alt="DKL Price component" />
</Frame>

`<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](/components/volume-picker/overview),
but reacts to the tier-change events the picker emits.

* When a [volume tier](/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

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/price/app-block">
    Add **DK: Price** in the theme editor and configure it with settings — no code.
  </Card>

  <Card title="Web Components" icon="code" href="/components/price/web-component">
    Drop `<dkl-price>` straight into your theme's Liquid and configure with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/price/styling-and-data">
    The `data-*` attributes, `--dkl-*` styling tokens, and CSS parts shared by both.
  </Card>

  <Card title="Events" icon="bell" href="/components/price/events">
    The tier-change and variant events `<dkl-price>` reacts to.
  </Card>
</CardGroup>

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

## 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/components/price/styling-and-data

The data-* attributes, CSS styling tokens, and CSS parts for <dkl-price>

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](/components/price/app-block) settings map onto these; on a [web component](/components/price/web-component) you set them directly.

<Note>
  **Using this reference with the app block**

  When you place the [**DK: Price** app block](/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](/components/price/web-component) only. To change block behaviour, use its [settings](/components/price/app-block).

  **CSS styling tokens — Yes:** T
  hey'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.
</Note>

<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.
</Tip>

## Data attributes

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

<ParamField type="int (cents)">
  The regular price — the component's base amount.
</ParamField>

<ParamField type="int (cents)">
  The native sale compare-at price. Struck through when no tier is active.
</ParamField>

<ParamField type="string">
  Money format string. Falls back to `Shopify.formatMoney`, then `Intl`.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  Show the savings badge (saving versus the original / highest price).
</ParamField>

<ParamField type="&#x22;percentage&#x22; | &#x22;amount&#x22;">
  How the savings badge displays the saving.
</ParamField>

<ParamField type="string">
  The badge's leading label, e.g. "**Save** 15%".
</ParamField>

<ParamField type="string">
  Connector between the sale saving and the tier saving, e.g. "Save 10% **+ an extra** 15%".
</ParamField>

<ParamField type="presence">
  **Set by the component** while a tier is active — a styling hook only. Don't author it yourself.
</ParamField>

## CSS styling tokens

<Frame>
  <img alt="Descriptive alt text" />
</Frame>

`<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).

<ParamField>
  Gap between price and compare-at.
</ParamField>

<ParamField>
  Font size for all price entities (main price, compare-at, savings badge)
</ParamField>

<ParamField>
  Main price font weight
</ParamField>

<ParamField>
  Main price color
</ParamField>

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

<ParamField>
  Struck-through compare-at opacity
</ParamField>

<ParamField>
  Compare-at font weight
</ParamField>

<ParamField>
  Compare-at color
</ParamField>

<ParamField>
  Compare-at text decoration
</ParamField>

<ParamField>
  Savings badge font size
</ParamField>

<ParamField>
  Savings badge font weight
</ParamField>

<ParamField>
  Savings badge text color
</ParamField>

<ParamField>
  Savings badge background color
</ParamField>

<ParamField>
  Savings badge corner radius
</ParamField>

<ParamField>
  Savings badge padding (vertical and horizontal)
</ParamField>

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

## CSS parts

<Frame>
  <img alt="Image highlighting the CSS parts for the DKL Price component" />
</Frame>

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

<ParamField type="CSSPart">
  The main price (the discounted price while a tier is active).
</ParamField>

<ParamField type="CSSPart">
  The struck-through compare-at wrapper.
</ParamField>

<ParamField type="CSSPart">
  The compare-at number.
</ParamField>

<ParamField type="CSSPart">
  The savings line wrapper.
</ParamField>

<ParamField type="CSSPart">
  The savings label text.
</ParamField>

<ParamField type="CSSPart">
  The savings amount.
</ParamField>

## Examples

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

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

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

## Next steps

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/price/app-block">
    Configure these via theme-editor settings.
  </Card>

  <Card title="Web Components" icon="code" href="/components/price/web-component">
    Set these directly on the tag.
  </Card>
</CardGroup>


# Web Component
Source: https://discountkit.app/components/price/web-component

Drop <dkl-price> into your theme markup and configure it with data-* attributes

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 theme={null}
<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.
</Tip>

<Warning>
  #### 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](/components/app-blocks-vs-web-components).
</Warning>

## 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](/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 theme={null}
// 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](/components/price/styling-and-data).

```liquid Override attributes + tokens theme={null}
<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 Listen for price changes theme={null}
// 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 Listen for tier changes theme={null}
// 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

<CardGroup>
  <Card title="Styling & Data Attributes" icon="palette" href="/components/price/styling-and-data">
    Every `data-*` attribute, `--dkl-*` token, and CSS part.
  </Card>

  <Card title="App block" icon="puzzle-piece" href="/components/price/app-block">
    The no-code, theme-editor placement.
  </Card>
</CardGroup>


# Roadmap
Source: https://discountkit.app/components/roadmap

What's planned and being explored for the Live Components

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.
</Note>

## In Progress

<Card title="Web Components for new Discount Types" icon="user-secret">
  We can't say much on this one yet, but we're working on it!
</Card>

<Card title="Gift with Purchase (GWP)" icon="gift">
  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.
</Card>

<Card title="Discount Price — subscriptions & selling plans" icon="repeat">
  `<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.
</Card>

<Card title="Discount Price — unit pricing" icon="scale-balanced">
  Surfacing unit price (`unit_price` / `unit_price_measurement`) alongside the main price, for
  stores that display per-unit pricing.
</Card>

## Exploration

<Card title="Blended Discounts within components" icon="merge">
  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.
</Card>

<Card title="Web Components in dynamic contexts" icon="window-restore">
  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](/components/app-blocks-vs-web-components).
</Card>

<Card title="Leaving beta" icon="circle-check">
  Hardening the components toward a stable, general-availability release.
</Card>

***

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


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

Add and configure the DK: Volume Groups block from the theme editor

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Edit a product template">Switch the top template selector to a **Product** template.</Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  #### Pairing with Discount Price

  To let [**DK: Price**](/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.
</Tip>

## Settings

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

### Discount & display

<ParamField type="metaobject">
  Show only this volume discount. Leave empty to show the first eligible one.
</ParamField>

<ParamField type="select">
  **Cards**, or **Mini buttons** (a compact grid; the per-tier price line is hidden).
</ParamField>

<ParamField type="text">
  Optional heading above the tiers.
</ParamField>

<ParamField type="text">
  Use `[tier_qty]` for the tier quantity.
</ParamField>

<ParamField type="text" />

<ParamField type="text" />

<ParamField type="text" />

### Behaviour

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

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

<ParamField type="checkbox">
  Bi-directional sync of the theme's quantity selector to the selected tier's quantity
</ParamField>

<ParamField type="text">
  Advanced: CSS selector for the theme's quantity input. Leave blank to auto-detect.
</ParamField>

<ParamField type="text">
  Advanced: Optional event name to trigger quantity sync.
</ParamField>

### Spacing & sizing

<ParamField type="range">
  Space above the widget, 0–80px.
</ParamField>

<ParamField type="range">
  Space below the widget, 0–80px.
</ParamField>

<ParamField type="select">
  **Inherit**, or **Custom** (reveals the sizes below).
</ParamField>

<ParamField type="range">
  10–32px. Custom only.
</ParamField>

<ParamField type="range">
  8–28px. Custom only.
</ParamField>

<ParamField type="range">
  Option corner radius, 0–24px.
</ParamField>

### Colors

<ParamField type="color" />

<ParamField type="color" />

<ParamField type="color">
  Resting card border.
</ParamField>

<ParamField type="color" />

<ParamField type="color" />

<ParamField type="color" />

<ParamField type="color">
  Border and ring of the selected tier.
</ParamField>

## Next steps

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/volume-picker/web-component">
    The same component placed by hand, configured with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/volume-picker/styling-and-data">
    The tokens, parts, and attributes behind these settings.
  </Card>
</CardGroup>


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

The event <dkl-volume-picker-radio-groups> emits

`<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>`](/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.
</Note>

<ParamField type="CustomEvent">
  Fired when a tier is selected or deselected. **Bubbles**, so you can listen on `document`.
  The detail carries `resource`:

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

<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>`](/components/price/overview) **ignore the tier for pricing** — but the event
  still fires, so your own integrations keep receiving it.

  [`<dkl-price>`](/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.
</Note>

A full example payload:

```js theme={null}
// 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.

<ParamField type="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.
</ParamField>

<ParamField type="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.
</ParamField>

```js theme={null}
// 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

<CardGroup>
  <Card title="Web Components" icon="code" href="/components/volume-picker/web-component">
    A listener example and how to react to tier changes.
  </Card>

  <Card title="Discount Price" icon="tag" href="/components/price/overview">
    The price display that reacts to this picker's tier-change events.
  </Card>
</CardGroup>


# Volume Picker
Source: https://discountkit.app/components/volume-picker/overview

PDP selector for volume / tiered discounts, one radio card per tier

<Tabs>
  <Tab title="Layout: Cards">
    <Frame>
      <img alt="Image highlighting the DKL Volume Picker component" />
    </Frame>
  </Tab>

  <Tab title="Layout: Mini-buttons">
    <Frame>
      <img alt="Image highlighting the DKL Volume Picker component - layout: mini-buttons" />
    </Frame>
  </Tab>
</Tabs>

`<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>`](/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

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/volume-picker/app-block">
    Add **DK: Volume Groups** in the theme editor and configure it with settings — no code.
  </Card>

  <Card title="Web Components" icon="code" href="/components/volume-picker/web-component">
    Drop `<dkl-volume-picker-radio-groups>` straight into your theme's Liquid and configure with `data-*`.
  </Card>

  <Card title="Styling & Data Attributes" icon="palette" href="/components/volume-picker/styling-and-data">
    The `data-*` attributes, `--dkl-*` styling tokens, CSS parts, and light-DOM classes shared by both.
  </Card>

  <Card title="Events" icon="bell" href="/components/volume-picker/events">
    The tier-change event `<dkl-volume-picker-radio-groups>` emits.
  </Card>
</CardGroup>

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

## 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/components/volume-picker/styling-and-data

The data-* attributes, CSS styling tokens, CSS parts, and light-DOM classes for <dkl-volume-picker-radio-groups>

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](/components/volume-picker/app-block) settings map onto
these; on a [web component](/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](/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](/components/volume-picker/web-component) only. To change block behaviour, use its [settings](/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.
</Note>

<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.
</Tip>

## Data attributes

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

<ParamField type="metaobject handle">
  Which discount's carrier to clone. The `discount-` prefix is optional; an attribute-less
  tag uses the default (first eligible).
</ParamField>

<ParamField type="&#x22;cards&#x22; | &#x22;mini-buttons&#x22;">
  Presentation: stacked cards, or a compact button grid (the per-tier price line is hidden).
</ParamField>

<ParamField type="string">
  Money format for JS-reformatted prices.
</ParamField>

<ParamField type="string">
  Instance id; disambiguates multiple widgets.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  Whether selecting a tier updates the displayed price — the theme's native price element and
  the [`<dkl-price>`](/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.
</ParamField>

<ParamField type="CSS selector | &#x22;none&#x22;">
  Override or disable the price element target. Use `"none"` when pairing with
  [`<dkl-price>`](/components/price/overview).
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  Sync the theme's quantity selector to the selected tier's quantity.
</ParamField>

<ParamField type="CSS selector | &#x22;none&#x22;">
  Override or disable the quantity input target.
</ParamField>

<ParamField type="event name">
  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.
</ParamField>

<ParamField type="&#x22;true&#x22; | &#x22;false&#x22;">
  Disable tiers when the variant is already on sale.
</ParamField>

<ParamField type="string">
  Label shown when a tier is unavailable.
</ParamField>

<Info>
  **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.
</Info>

<Accordion title="Per-tier attributes (data-dkl-*)" icon="layer-group">
  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.

  <ParamField type="int">
    The tier's position in the group.
  </ParamField>

  <ParamField type="&#x22;percentage&#x22; | &#x22;fixedAmount&#x22;">
    How the tier's discount is expressed.
  </ParamField>

  <ParamField type="number">
    The fixed discount amount (when `fixedAmount`).
  </ParamField>

  <ParamField type="number">
    The discount percent (when `percentage`).
  </ParamField>

  <ParamField type="int (cents)">
    The pre-computed discounted unit price.
  </ParamField>
</Accordion>

## CSS styling tokens

<Tabs>
  <Tab title="Layout: Cards">
    <Frame>
      <img alt="Image highlighting the CSS styling tokens for the DKL Volume Picker component" />
    </Frame>
  </Tab>

  <Tab title="Layout: Mini-buttons">
    <Frame>
      <img alt="Image highlighting the CSS styling tokens for the DKL Volume Picker component" />
    </Frame>
  </Tab>
</Tabs>

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](/components/overview#global-brand-tokens) so cards match the theme.

### Structure

<ParamField>
  Space below the title row.
</ParamField>

<ParamField>
  Group title font weight.
</ParamField>

<ParamField>
  Group title font size.
</ParamField>

<ParamField>
  Group title color.
</ParamField>

<ParamField>
  Gap between options.
</ParamField>

<ParamField>
  Mini-buttons grid columns.
</ParamField>

<ParamField>
  Mini-buttons option padding.
</ParamField>

<ParamField>
  Border and ring of the **selected** tier.
</ParamField>

<ParamField>
  Resting card border.
</ParamField>

<ParamField>
  Card corners.
</ParamField>

<ParamField>
  Card background.
</ParamField>

<ParamField>
  Hover background.
</ParamField>

<ParamField>
  Focus-visible outline.
</ParamField>

## CSS parts and classes

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

### Parts

<Tabs>
  <Tab title="Layout: Cards">
    <Frame>
      <img alt="Image highlighting the CSS parts for the DKL Volume Picker component" />
    </Frame>
  </Tab>

  <Tab title="Layout: Mini-buttons">
    <Frame>
      <img alt="Image highlighting the CSS parts for the DKL Volume Picker component - layout: mini-buttons" />
    </Frame>
  </Tab>
</Tabs>

<ParamField type="CSSPart">
  The `<fieldset>` wrapper.
</ParamField>

<ParamField type="CSSPart">
  The title row.
</ParamField>

<ParamField type="CSSPart">
  The `<legend>` group title.
</ParamField>

<ParamField type="CSSPart">
  The radiogroup holding the options.
</ParamField>

### Light-DOM classes

<ParamField type="class">
  One tier card (selected: `:has(.dkl-volume-picker__radio:checked)`).
</ParamField>

<ParamField type="class">
  The radio input.
</ParamField>

<ParamField type="class">
  Card inner row.
</ParamField>

<ParamField type="class">
  Title + discount stack.
</ParamField>

<ParamField type="class">
  Tier heading (e.g. "Buy 3+").
</ParamField>

<ParamField type="class">
  The "X% off each" line.
</ParamField>

<ParamField type="class">
  Per-tier price.
</ParamField>

<ParamField type="class">
  The unit suffix (e.g. "/ea").
</ParamField>

<ParamField type="class">
  "No discount" placeholder.
</ParamField>

## Examples

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

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

```html Compact button layout theme={null}
<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

<CardGroup>
  <Card title="App block" icon="puzzle-piece" href="/components/volume-picker/app-block">
    Configure these via theme-editor settings.
  </Card>

  <Card title="Web Components" icon="code" href="/components/volume-picker/web-component">
    Set these directly on the tag.
  </Card>
</CardGroup>


# Web Component
Source: https://discountkit.app/components/volume-picker/web-component

Drop <dkl-volume-picker-radio-groups> into your theme markup and configure it with data-* attributes

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 theme={null}
<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 theme={null}
<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](/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](/components/volume-picker/styling-and-data).

```html Override attributes + tokens theme={null}
<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 Pair with <dkl-price> theme={null}
<!-- 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 Listen for tier changes theme={null}
// 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 Example event payload theme={null}
// 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

<CardGroup>
  <Card title="Styling & Data Attributes" icon="palette" href="/components/volume-picker/styling-and-data">
    Every `data-*` attribute, `--dkl-*` token, CSS part, and light-DOM class.
  </Card>

  <Card title="App block" icon="puzzle-piece" href="/components/volume-picker/app-block">
    The no-code, theme-editor placement.
  </Card>
</CardGroup>


# Common settings
Source: https://discountkit.app/discounts/common-settings

Settings shared across all discount types

#### 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.
</Note>

<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.
</Tip>

#### Customer eligibility

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

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

#### 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](/discounts/custom), you can also set market conditions
  at the proposal level to target different markets with different offers.
</Tip>

#### Location eligibility

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

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

#### 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.
</Tip>

#### 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"`.
</Tip>

#### 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](/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](/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/discounts/custom

Build custom discount logic for unique promotional needs

## Setup

<Steps>
  <Step title="Open your store's Discounts page and click Create discount">
    <Frame>
      <img alt="Create new discount image" />
    </Frame>
  </Step>

  <Step title="Scroll down to the Discount Kit section, which should now be available, and click Custom">
    <Frame>
      <img alt="Select custom image" />
    </Frame>
  </Step>

  <Step title="Configure your desired settings and click Save">
    <Frame>
      <img alt="Save custom image" />
    </Frame>
  </Step>
</Steps>

## 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.
</Note>

#### 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](/discounts/common-settings). Both must be satisfied for the discount to apply.
</Note>

#### 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.
</Note>

### 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`.
</Note>

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.

<Frame>
  <img alt="Example metafield configuration with array format" />
</Frame>

## Integrations

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


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

Offer free gifts when customers meet purchase requirements

## Setup

<Steps>
  <Step title="Open your store's Discounts page and click Create discount">
    <Frame>
      <img alt="Create new discount image" />
    </Frame>
  </Step>

  <Step title="Scroll down to the Discount Kit section, which should now be available, and click Gift with purchase">
    <Frame>
      <img alt="Select gift with purchase image" />
    </Frame>
  </Step>

  <Step title="Fill in the desired settings and click Save">
    <Frame>
      <img alt="Save gift with purchase image" />
    </Frame>
  </Step>
</Steps>

## 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.

<Warning>
  **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.
</Warning>

**Manually Refreshing the Cart:**

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

```javascript theme={null}
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.

<Frame>
  <img alt="Auto gift setup image" />
</Frame>

**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**.

<Frame>
  <img alt="Don't re-add manually removed gifts setting" />
</Frame>

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.

<Frame>
  <img alt="Gift selector setup image" />
</Frame>

#### 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 theme={null}
{
  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 theme={null}
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/discounts/localized-messages

Override discount messages with translations for all available store locales

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

<Steps>
  <Step title="Create or edit an automatic discount">
    Navigate to your discount configuration and ensure the discount method is set to Automatic.
  </Step>

  <Step title="Find the title override field">
    Scroll to the tier settings where you can set an override title.
  </Step>

  <Step title="Click the translate button">
    <Frame>
      <img alt="Translate button" />
    </Frame>

    Click the translate button that appears inside the title override field.
  </Step>

  <Step title="Choose a language">
    <Frame>
      <img alt="Localise menu" />
    </Frame>

    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save your changes">
    Click Save to apply your changes.
  </Step>
</Steps>

## 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/discounts/order-volume

Provide discounts when customers reach spending thresholds

## Setup

<Steps>
  <Step title="Open your store's Discounts page and click Create discount">
    <Frame>
      <img alt="Create new discount image" />
    </Frame>
  </Step>

  <Step title="Scroll down to the Discount Kit section, which should now be available, and click Order goal">
    <Frame>
      <img alt="Select order goal image" />
    </Frame>
  </Step>

  <Step title="Configure your desired settings and click Save">
    <Frame>
      <img alt="Save order goal image" />
    </Frame>
  </Step>
</Steps>

## 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.

<Frame>
  <img alt="Exclude collection interface" />
</Frame>

#### Exclude products with compare at prices

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

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

### 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.

<Frame>
  <img alt="Setup order goal banner image" />
</Frame>


# Product volume
Source: https://discountkit.app/discounts/product-volume

Offer tiered discounts based on quantity purchased

## Setup

<Steps>
  <Step title="Open your store's Discounts page and click Create discount">
    <Frame>
      <img alt="Create new discount image" />
    </Frame>
  </Step>

  <Step title="Scroll down to the Discount Kit section, which should now be available, and click Product volume">
    <Frame>
      <img alt="Select product volume image" />
    </Frame>
  </Step>

  <Step title="Configure your desired settings and click Save">
    <Frame>
      <img alt="Save product volume image" />
    </Frame>
  </Step>
</Steps>

## 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.

<Frame>
  <img alt="Volume table setup image" />
</Frame>

#### 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!

<Frame>
  <img alt="Bundle selector setup image" />
</Frame>


# Stacking discounts
Source: https://discountkit.app/discounts/stacking

Control which discounts can apply together — across discount classes and on the same cart line

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.
</Tip>

## Combining on the same cart line

<Note>
  This feature is only available on **Shopify Plus** plans.
</Note>

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](/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.

## Stacking and Discount Kit Live

[Discount Kit Live](/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/documentation

Advanced discounts for Shopify with instant storefront access

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

<CardGroup>
  <Card title="Introduction to Live" icon="bolt" href="/live/introduction">
    Learn about Discount Kit Live features
  </Card>

  <Card title="Storefront Data" icon="database" href="/live/storefront-data">
    Access discount data in your theme
  </Card>

  <Card title="Examples" icon="code" href="/live/examples">
    Copy-paste code for badges, pricing, and banners
  </Card>

  <Card title="Data reference" icon="book" href="/live/reference">
    Complete field reference documentation
  </Card>
</CardGroup>


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

Why percentage discounts on low unit prices don't always match the expected total

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.
</Tip>


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

Export and share discount logs with our support team

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

<Steps>
  <Step title="Click the overflow menu and select Manage app">
    <Frame>
      <img alt="Manage app menu" />
    </Frame>
  </Step>

  <Step title="Scroll to the bottom and click Share logs">
    <Frame>
      <img alt="Share logs button" />
    </Frame>
  </Step>
</Steps>


# Home
Source: https://discountkit.app/index



<div>
  <div>
    <div>
      <h1>
        Craft discount experiences
      </h1>

      <p>
        Build powerful discount experiences with instant storefront access to discount data. No API calls, no loops, blazing fast.
      </p>

      <div>
        <div>
          <img alt="5 stars" />

          <span>1,000+ happy brands</span>
        </div>

        <Tooltip>
          <div>
            <img alt="Built for Shopify" />

            <img alt="Built for Shopify" />
          </div>
        </Tooltip>
      </div>

      <div>
        <a href="https://apps.shopify.com/discount-kit">
          <img alt="Available on Shopify App Store" />

          <img alt="Available on Shopify App Store" />
        </a>
      </div>
    </div>

    <div>
      <div>
        <div>
          <img alt="Discount Kit Example" />
        </div>
      </div>
    </div>
  </div>
</div>

<div>
  <h3>
    trusted by global brands
  </h3>

  <div>
    <div>
      <div>
        <img alt="Dr. Squatch" />

        <img alt="LARQ" />

        <img alt="Ruggable" />

        <img alt="Therabody" />

        <img alt="TRTL" />

        <img alt="Casper" />

        <img alt="Mejuri" />

        <img alt="Kitsch" />

        <img alt="The Body Shop" />

        <img alt="Champion" />
      </div>

      <div>
        <img alt="Dr. Squatch" />

        <img alt="LARQ" />

        <img alt="Ruggable" />

        <img alt="Therabody" />

        <img alt="TRTL" />

        <img alt="Casper" />

        <img alt="Mejuri" />

        <img alt="Kitsch" />

        <img alt="The Body Shop" />

        <img alt="Champion" />
      </div>
    </div>
  </div>

  <div>
    <div>
      <div>
        <img alt="Decathlon" />

        <img alt="Davids Tea" />

        <img alt="Beast" />

        <img alt="Micro" />

        <img alt="Oddballs" />

        <img alt="O'Neal" />

        <img alt="Pro:Direct" />

        <img alt="Bombay Saphire" />

        <img alt="Spyder" />

        <img alt="Unilever" />
      </div>

      <div>
        <img alt="Decathlon" />

        <img alt="Davids Tea" />

        <img alt="Beast" />

        <img alt="Micro" />

        <img alt="Oddballs" />

        <img alt="O'Neal" />

        <img alt="Pro:Direct" />

        <img alt="Bombay Saphire" />

        <img alt="Spyder" />

        <img alt="Unilever" />
      </div>
    </div>
  </div>
</div>


# Examples
Source: https://discountkit.app/live/examples

Copy-paste implementations for common use cases

## Quick Start: Best Discount Badge

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

<Tabs>
  <Tab title="Preview">
    <Frame>
      <img alt="Product card with red '20% OFF' badge in top-right corner" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

<Tip>
  This approach is simpler than parsing the full discounts array and automatically shows the **best** available discount.
</Tip>

***

### Best Discount with Title

Show both the discount value and title using `max_reward_discount`:

<Tabs>
  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

***

## Sales Badges

### Simple Percentage Badge

<Tabs>
  <Tab title="Preview">
    <Frame>
      <img alt="Product card with red '20% OFF' badge in top-right corner" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

***

## Pricing Display

### Crossed-Out Original Price

<Tabs>
  <Tab title="Preview">
    <Frame>
      <img alt="Product pricing showing original price crossed out in gray and sale price in red" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

***

## Volume Pricing Table

<Tabs>
  <Tab title="Preview">
    <Frame>
      <img alt="Product with info icon next to title and volume pricing popup showing quantity tiers and discounted prices" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

***

## 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 theme={null}
{% 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).
</Tip>

### 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 theme={null}
{%- 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.
</Note>

### Mix: Auto-Applied vs Code-Entry Badge

Render different UI depending on how the discount is redeemed:

```liquid theme={null}
{% 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

<Tabs>
  <Tab title="Preview">
    <Frame>
      <img alt="Collection page with red banner displaying 'PLANTS DISCOUNT Save up to 20% on this collection!'" />
    </Frame>
  </Tab>

  <Tab title="Code">
    ```liquid theme={null}
    {% 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 %}
    ```
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Data reference" icon="book" href="/live/reference">
    Complete field documentation
  </Card>

  <Card title="Introduction" icon="rocket" href="/live/introduction">
    Learn about Discount Kit Live
  </Card>
</CardGroup>


# Filtering discounts
Source: https://discountkit.app/live/filtering-discounts

Filter discounts by method, markets, customer tags, and cart state in your Liquid templates

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.
</Note>

## 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 theme={null}
{% 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 theme={null}
{%- 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.
</Note>

## 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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](/live/storefront-data)
* View complete [examples](/live/examples)
* Check the full [reference](/live/reference)


# Introduction
Source: https://discountkit.app/live/introduction

Real-time discount data available instantly in your storefront

Discount Kit 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

Discount Kit 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 Discount Kit or anywhere else in your admin.

* **To include** a discount in Discount Kit Live: add the tag `dk:live`.
* **To exclude** a discount: remove the tag.

<Frame>
  <img alt="Animation showing the dk:live tag being added in the Tags field of a Shopify discount edit page" />
</Frame>

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, Discount Kit 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 Discount Kit Live.
</Note>

## Discount Limits

Discount Kit 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 before this PR the 25 cap was effectively invisible.
* With code-based discounts now supported, the cap matters: if you tag 5 automatic + 30 code discounts with `dk:live`, only 25 of them will appear in Discount Kit 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 Discount Kit 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, Discount Kit 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, Discount Kit 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 Discount Kit Live

If you need to show segment-specific discounts in your storefront, consider using customer tags as an alternative targeting method.

## Getting Started

<CardGroup>
  <Card title="Settings" icon="sliders" href="/live/settings">
    Control what LIVE syncs to your storefront
  </Card>

  <Card title="Storefront Data" icon="bolt" href="/live/storefront-data">
    Learn how to access discount data in your theme
  </Card>

  <Card title="Examples" icon="code" href="/live/examples">
    Copy-paste code for badges, pricing, and banners
  </Card>

  <Card title="Data reference" icon="book" href="/live/reference">
    Complete field reference documentation
  </Card>

  <Card title="Filtering discounts" icon="filter" href="/live/filtering-discounts">
    Filter discounts by method, market, customer tags, or applied codes
  </Card>
</CardGroup>


# Data reference
Source: https://discountkit.app/live/reference

Complete DiscountSummary field documentation

## 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`.
</Note>

<Warning>
  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.
</Warning>

### max\_reward\_percent

**Type:** `number_decimal`

The best percentage discount value available for this product/collection.

```liquid theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{{ 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{{ discount.minimum_threshold_value }}
```

### threshold\_product\_references

**Type:** `list.product_reference`

Products that count toward the threshold.

```liquid theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
<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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{%- 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.
</Note>

***

## 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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.
</Note>

### 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% if discount.config %}
  {% assign config_data = discount.config.value %}
  {%- comment -%} Use with caution - structure varies {%- endcomment -%}
{% endif %}
```

***

## TypeScript Type

```typescript theme={null}
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

<CardGroup>
  <Card title="Code Examples" icon="code" href="/live/examples">
    Practical implementations
  </Card>

  <Card title="Introduction" icon="rocket" href="/live/introduction">
    Learn about Discount Kit Live
  </Card>
</CardGroup>


# Settings
Source: https://discountkit.app/live/settings

Control what LIVE syncs to your storefront

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.

<Frame>
  <img alt="LIVE sync settings popover showing toggles for LIVE sync, Product metafields, Collection metafields, and Collection fan-out" />
</Frame>

## 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.
</Note>

## 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/live/storefront-data

Access discount data through product, collection, and shop metafields

Discount Kit 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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](/live/reference) 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, Discount Kit 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`.
</Note>

<Warning>
  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. See the [data reference](/live/reference) for details.
</Warning>

### 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 theme={null}
{% 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 theme={null}
{% 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 theme={null}
{% 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

* Learn about [filtering discounts](/live/filtering-discounts) by method, market, customer tags, and cart state
* See the complete [DiscountSummary reference](/live/reference)
* Explore [code examples](/live/examples)


# Enterprise Support Policy
Source: https://discountkit.app/policies/enterprise-support-policy

Enterprise Support Policy for Discount Kit

**Effective Date:** 6th January 2026
**Last Updated:** 6th January 2026

## 1. Introduction

This Enterprise Support Policy outlines the enhanced support framework provided exclusively to customers subscribed to the Discount Kit Enterprise Plan. It details the mechanisms for communication, the scope of our dedicated support channels, and our commitments to responsiveness and collaboration.

## 2. Dedicated Slack Connect Channel

### 2.1 Purpose & Scope

The Slack Connect channel is a premium collaboration tool designed to bridge the gap between your team and Optizio's product and engineering experts. Unlike standard support tickets, this channel is intended for:

* **Rapid Consultation:** Quick questions about configuration, strategy, or API usage.
* **Direct Collaboration:** Real-time discussion with our Product Managers and Engineers during complex implementations.
* **Incident Coordination:** A centralized war room for communication during critical incidents.

### 2.2 Terms of Use

To ensure this channel remains effective for high-value interactions:

* **Appropriate Usage:** The channel is not a replacement for formal bug reporting (see *Issue Resolution Policy*). While issues can be discussed here, formal tracking may still require a ticket reference.
* **Participation:** The channel includes access to Support Engineers, Product Managers, and Technical Leads. It is not staffed by Level 1 support agents.
* **Availability:** While the channel is always open, real-time responses are provided during our engineering working hours. Messages sent out of hours will be addressed priority first when engineers/product managers become available.

## 3. Support Tiers & Escalation

### 3.1 Standard Support vs. Enterprise Support

Enterprise customers bypass the standard Level 1 support queue for all technical inquiries.

* **Standard Support:** Handling of general billing, basic setup, and FAQ inquiries, out of hours support, and critical incident reporting.
* **Enterprise Support:** Direct routing to Senior Support Engineers and Technical Leads for complex logic configuration, script debugging, and performance optimization.

### 3.2 Escalation Matrix

If an issue is not progressing according to the timelines defined in our SLA, or if the business impact increases significantly, the following escalation path is available via your Slack channel:

| Level       | Role                    | Trigger Condition                                                                 |
| :---------- | :---------------------- | :-------------------------------------------------------------------------------- |
| **Level 1** | Senior Support Engineer | Initial contact for all technical queries.                                        |
| **Level 2** | Technical Lead          | Issue unresolved after initial investigation or requires code-level analysis.     |
| **Level 3** | Head of Product / CTO   | Critical business impact, recurring SLA breach, or strategic roadmap discussions. |

Depending on who is available, it may be the case that you will directly speak to any one of these levels without requiring escalation.

## 4. Proactive Monitoring & Account Management

### 4.1 Proactive Health Checks

For Enterprise merchants, Optizio implements proactive monitoring alerts specifically for your store's high-volume events (e.g., Black Friday, major flash sales).

* **Requirement:** Customers must notify Optizio via Slack at least 7 days prior to anticipated traffic spikes >5x normal volume.
* **Action:** We will review your discount configurations for performance bottlenecks and monitor your specific error rates during the event.

### 4.2 Quarterly Business Reviews (QBR)

(Optional) Upon request, Enterprise customers are eligible for a quarterly strategic review call to:

* Discuss upcoming roadmap features.
* Review recent support cases and resolution quality.
* Audit current discount logic for optimization opportunities.

## 5. Implementation & Migration Support

We provide hands-on assistance during your onboarding phase:

* **Script Migration:** Assistance converting legacy Shopify Scripts or competitor logic into Discount Kit Functions.
* **Staging Environment Support:** Full support coverage for your development/staging stores to ensure smooth testing before production rollout.

***

**Optizio Ltd**
124 City Road, London, EC1V 2NX, United Kingdom
Contact: [support@discountkit.app](mailto:support@discountkit.app)


# Issue Resolution Policy
Source: https://discountkit.app/policies/issue-resolution-policy

Issue Resolution & Prioritization Policy for Discount Kit

**Effective Date:** 6th January 2026
**Last Updated:** 6th January 2026

## 1. Introduction

This policy establishes the framework for how Optizio Ltd classifies, prioritizes, and resolves reported issues for Discount Kit Enterprise Plan customers. It is designed to ensure transparency in our roadmap and fairness in our resource allocation, distinguishing clearly between unintended software defects ("Bugs") and requests for new capabilities ("Feature Requests").

## 2. Issue Classification

To ensure issues are routed to the correct engineering workflows, all reports are classified into one of the following categories. **Optizio reserves the right to reclassify issues** that are reported as bugs but meet the definition of a feature request or limitations.

### 2.1 Bug (Defect)

An unintended failure of the software to perform as designed or documented.

* **Examples:**
  * A discount rule configured to take 10% off is taking 0% off.
  * The application crashes or throws a 500 error during normal operation.
  * A documented API endpoint returns an invalid response format.
* **Handling:** Prioritized based on severity and SLA impact.

### 2.2 Feature Request

A request for behavior, functionality, or logic that does not currently exist in the application, or a change to existing intended behavior to suit a specific preference.

* **Examples:**
  * "I want the discount to apply before tax instead of after." (If the system is designed to apply after tax).
  * "Add a new condition to filter by Customer Metafields."
* **Handling:** Added to the Product Backlog for prioritization (see Section 4).

### 2.3 Known Limitation / Architecture Constraint

A behavior that is acknowledged but is a result of platform constraints (e.g., Shopify API limits) or core architectural decisions. These are not considered bugs.

* **Examples:**
  * Latency caused by Shopify's APIs.
  * Inability to stack specific Shopify automatic discounts due to native platform restrictions.
* **Handling:** Documented as a known behavior; may be considered for long-term architectural refactoring but not subject to standard bug fix timelines.

## 3. Bug Prioritization & Resolution

Bugs are triaged based on their impact on your business and the severity of the malfunction.

| Severity     | Definition                                                                                                                                             | Target Resolution                                                         |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ |
| **Critical** | **System Down / Revenue Blocked.** Core discounting logic is failing for all or a significant subset of customers. No workaround exists.               | Immediate engineering focus until resolved. (See SLA for response times). |
| **Major**    | **Feature Broken.** A specific feature is not working (e.g., "Buy X Get Y" logic fails), but other discount types work. A workaround may be difficult. | Scheduled for next immediate patch release or hotfix (typically 24-48h).  |
| **Minor**    | **Cosmetic / Nuisance.** UI glitches, typos, or minor errors that do not affect the calculation of price or checkout completion.                       | Scheduled for next standard release cycle (typically weekly/bi-weekly).   |

## 4. Feature Request Prioritization

We value customer feedback and our roadmap is heavily influenced by Enterprise merchant needs. However, **reporting a feature request as a bug will not expedite its delivery.** Feature requests are prioritized using a weighted scoring model:

1. **Customer Impact:** How many customers will benefit? Does this unblock a significant revenue opportunity for the requester?
2. **Strategic Fit:** Does this align with our long-term product vision?
3. **Engineering Effort:** Complexity and maintenance cost.

### 4.1 Enterprise Priority

Enterprise Plan customers receive **weighted priority** in this scoring model. Your requests are reviewed directly by the Product Manager during regular planning.

### 4.2 Status Communication

We will communicate the status of your requests as:

* **Accepted:** Scheduled for development (with estimated quarter).
* **Under Consideration:** Added to backlog for future review.
* **Not Planned:** We will not proceed with this request (e.g., due to technical infeasibility or conflict with core product direction).

## 5. Complex & Architectural Issues

Occasionally, an issue may be "valid" (a real problem for you) but "complex" (requiring months of re-architecture or conflicting with other customers' needs).

In these cases:

1. **Transparent Assessment:** We will provide a detailed technical explanation of why the issue exists and why a quick fix is not possible.
2. **Workaround Engineering:** Our Solution Engineers will work with you to find alternative ways to achieve your business goal using existing functionality.
3. **Long-Term Roadmap:** If the issue represents a significant blocker, it may be added to our long-term roadmap, but it will be explicitly excluded from standard SLA resolution timelines.

***

**Optizio Ltd**
124 City Road, London, EC1V 2NX, United Kingdom
Contact: [support@discountkit.app](mailto:support@discountkit.app)


# Privacy policy
Source: https://discountkit.app/policies/privacy-policy

Privacy and data handling policy for Discount Kit

**Last Updated:** July 21, 2025

This privacy policy governs the Discount Kit Shopify application operated by Optizio Ltd.

## Company Details

* **Organization:** Optizio Ltd
* **Location:** 124 City Road, London, EC1V 2NX, United Kingdom
* **Data Protection Officer:** David Spanton
* **Support Contact:** [support@discountkit.app](mailto:support@discountkit.app)

## Information We Collect

### Merchant Store Information

* Store names, URLs, and Shopify identifiers
* Staff member details
* Configuration data for discount functionality

### What We Don't Collect

We do not collect personal data from your customers (end-users) and avoid processing payment card information.

## How We Use Your Information

We use the collected information to:

* Provide and maintain the Discount Kit service
* Offer customer support and respond to inquiries
* Send product communications and updates
* Analyze performance and improve our service
* Ensure security and prevent fraud

## Legal Bases for Processing

### GDPR Regions

Processing is based on legitimate interest and contract performance.

### Consent-Based Regions

For Brazil, India, and South Korea, explicit consent is obtained during setup.

### US States

Processing is based on legitimate interest with jurisdiction-specific consent where needed.

## Data Sharing

We partner with:

* **Cloudflare:** Session storage
* **Mantle:** Operations platform
* **Intercom:** Customer support

**Important:** We do not sell, rent, or trade your personal information and explicitly avoid sharing with advertisers.

## Data Security

Our security framework includes:

* AES-256 encryption
* Multi-factor authentication
* Regular software updates
* Continuous threat monitoring
* Alignment with Shopify's development standards

## Data Retention and Deletion

* **Configuration data:** Deleted automatically upon app uninstallation
* **Support records:** Retained for three years post-interaction
* **Legal requirements:** Some data may be retained as required by law

## Your Rights

You have the right to:

* Access your personal data
* Request correction of inaccurate data
* Request deletion of your data
* Request data portability
* Withdraw consent (where applicable)
* Restrict processing (GDPR users)

### GDPR Rights

If you're in the EU/EEA, you have additional rights under GDPR including the right to lodge a complaint with a supervisory authority.

### US State Privacy Rights

Residents of California (CCPA/CPRA), Virginia (VCDPA), Colorado (CPA), Connecticut (CTDPA), and Utah (UCPA) have specific privacy protections under state law.

### Other Jurisdictions

We comply with PIPEDA (Canada) and COPPA (US children's privacy) requirements.

## International Data Transfers

Data may be transferred and processed in locations outside your jurisdiction. We implement appropriate safeguards to ensure your data remains protected.

## Changes to This Policy

We may update this Privacy Policy from time to time. Material changes will be communicated via email or app notifications. Continued use after changes constitutes acceptance.

## Contact Us

For questions about this Privacy Policy or to exercise your rights, please contact us at:

**Email:** [support@discountkit.app](mailto:support@discountkit.app)

**Optizio Ltd**
124 City Road
London
EC1V 2NX
United Kingdom


# Service level agreement
Source: https://discountkit.app/policies/sla

Service Level Agreement for Discount Kit Enterprise Plan

**Effective Date:** July 22, 2025
**Last Updated:** January 6, 2026

**Scope:** This SLA applies to Discount Kit Enterprise Plan subscribers only.

## 1. Service Availability & Uptime

### Uptime Commitment

We maintain a **99.9% uptime** target monthly, permitting approximately 43 minutes of downtime.

### Planned Maintenance

A minimum of 48 hours' notice precedes scheduled maintenance, typically scheduled during low-traffic periods. Emergency maintenance may proceed immediately when necessary.

### Excluded from SLA

The following circumstances are excluded from SLA calculations:

* Third-party outages (Shopify, Cloudflare)
* Force majeure circumstances
* Customer configuration errors
* External connectivity problems
* Properly-announced maintenance windows

### Monitoring

Uptime tracking uses Instatus, Sentry, and Cloudflare tools measuring core functionality availability.

## 2. Performance Metrics

### Page Load Standards

Our commitment aligns with Shopify's "Built for Shopify" criteria:

* **Largest Contentful Paint:** Under 2.5 seconds
* **Cumulative Layout Shift:** Under 0.1
* **Interaction to Next Paint:** Under 200 milliseconds

### Measurement Approach

Shopify Insights provides real-world performance data aggregated globally across all user locations.

## 3. Support & Response Times

### Available Channels

* In-app chat and email (all plans)
* Dedicated shared Slack channel (Enterprise exclusive). **Full details on the usage and scope of this channel are defined in the [Enterprise Support Policy](enterprise-support-policy).**

### Support Hours

* **Current:** 24/7, 365 support

### Response Time Commitments

| Priority     | Description                                            | Business Hours  | After Hours       |
| ------------ | ------------------------------------------------------ | --------------- | ----------------- |
| **Critical** | Complete unavailability or major functionality failure | 30 minutes      | 2 hours           |
| **High**     | Significant functionality impact without workaround    | 12 hours        | Next business day |
| **Low**      | Questions, feature requests, general inquiries         | 3 business days | 3 business days   |

**Important Notes:**

* Optizio determines priority classification. **Issues are classified as Bugs or Feature Requests in accordance with our [Issue Resolution & Prioritization Policy](issue-resolution-policy).**
* Response times begin with substantive replies, not automated acknowledgments
* The dedicated Slack channel enables faster escalation **as outlined in the [Enterprise Support Policy](enterprise-support-policy).**

## 4. Data & Security

### Data Protection

Our commitments align with our Data Backup Policy, Information Security Policy, and Privacy Policy.

### Security Standards

* AES-256 encryption for stored data
* TLS 1.2+ for data transmission
* Role-based access controls
* Multi-factor authentication on critical systems
* Full GDPR and Data Protection Act 2018 compliance

### Incident Response

Security events trigger notification per the Incident Response Plan, with customer notification within 72 hours when legally required.

**Note:** Enterprise customers receive identical security standards as other plan tiers.

## 5. Service Credits & Remedies

### Eligibility

Credits apply exclusively to Enterprise Plan subscribers.

### Credit Structure

**10% of monthly subscription fees for each SLA breach** with accumulation possible up to 100% monthly fees. All breach types yield identical credit amounts.

### Process

* Customers must request credits (not automatic)
* Claims require submission within 3 months
* Credits apply to the following month's subscription as a Shopify application credit
* Supporting documentation of the breach strengthens requests

### Excluded Circumstances

Credits don't apply to:

* Third-party outages
* Force majeure
* Customer misuse
* External connectivity issues
* Properly-announced maintenance

### Termination Rights

Customers may terminate without early-exit penalties when:

* Three consecutive months show SLA breaches, **OR**
* Four or more breaches occur within any six-month window

Termination requires 30 days' written notice and documentation of qualifying breaches. Optizio refunds unused current-period fees.

## 6. SLA Measurement and Reporting

### Monitoring Approach

* Continuous uptime tracking via three platforms
* Performance measurement through Shopify Insights
* Support response timing through internal ticketing systems

### Reporting

* Monthly performance summaries available upon request
* Proactive communication for significant disruptions
* Transparent status page access

## 7. SLA Modifications

We may update this agreement with 30 days' advance notice. Material modifications receive email and in-app notification. Continued service use indicates acceptance of changes.

Annual reviews may prompt updates reflecting infrastructure improvements or business requirements.

## 8. Contact Information

**Support Email:** [support@discountkit.app](mailto:support@discountkit.app)

**Optizio Ltd**
124 City Road
London
EC1V 2NX
United Kingdom

Enterprise Plan Slack channel details provided upon activation.


# Terms of service
Source: https://discountkit.app/policies/terms-of-service

Terms and conditions for using Discount Kit

**Last Updated:** August 25, 2025

These Terms and Conditions ("Agreement") govern use of the Discount Kit Shopify application ("App"), provided by Optizio Ltd. By installing or using the App, you agree to be bound by this Agreement. Non-acceptance means you should not install or use the App.

## 1. Description of Service

The App provides discounting functionality for Shopify stores, allowing users to create, manage, and apply discounts to products and orders.

## 2. Eligibility

Users must be at least 18 years old and possess authority to enter into this Agreement on behalf of their business or entity.

## 3. Shopify Account

Active Shopify account ownership and compliance with Shopify's terms are required. The provider assumes no responsibility for Shopify relationships or third-party services.

## 4. License

A limited, non-exclusive, non-transferable, revocable license is granted for internal business purposes connected to your Shopify store.

## 5. User Responsibilities

Users agree to:

* Comply with applicable laws and Shopify policies
* Refrain from misuse, reverse engineering, or unauthorized access attempts
* Maintain accurate and current information

## 6. Fees and Payment

Fees follow the Shopify App Store listing specifications. Shopify's billing system handles all payments.

## 7. Discount Functionality

Users bear sole responsibility for discount configuration and legal compliance. The provider disclaims liability for discount application errors or pricing issues.

## 8. Data and Privacy

Data collection and usage follow the Privacy Policy on the Shopify App Store listing. Installation constitutes consent to such practices.

## 9. Intellectual Property

Optizio Ltd retains all intellectual property rights. Users cannot copy, modify, or distribute App content without written consent.

## 10. Termination

### 10.1 Mutual Termination

Either party may terminate through:

* (a) written notice if the other materially breaches and fails to remedy within 30 days; or
* (b) immediate notice upon insolvency, creditor assignment, or bankruptcy filing

### 10.2 Client Termination

Users may terminate anytime by uninstalling the App.

### 10.3 Optizio Termination

The provider may terminate:

* (a) with 30 days' notice for convenience
* (b) immediately for security-risk breaches under Section 5
* (c) immediately for non-payment beyond 15 days' notice

### 10.4 Termination Effects

* License ceases immediately
* Users remain liable for pre-termination fees
* Data deletion or return occurs within 90 days per Privacy Policy (except legally required retention)
* Sections 9, 12, 13, 13A, and 15 survive termination

## 11. Disclaimer of Warranties

The App is provided "as is" and "as available" without warranties of any kind, express or implied. Error-free or uninterrupted operation is not guaranteed.

## 12. Limitation of Liability

### 12.1

Indirect, incidental, special, consequential, or punitive damages are excluded, including profit or revenue loss.

### 12.2

Aggregate liability caps apply:

* Provider liability limited to 200% of fees paid in preceding 12 months (excluding confidentiality breaches)
* User liability capped at 100% of fees paid in preceding 12 months

## 13. Client Indemnification

Users indemnify and defend Optizio Ltd against claims, damages, or expenses arising from App use or Agreement violations.

## 13A. Optizio Indemnification

### 13A.1

The provider defends against third-party claims involving:

* Material data protection breaches under the Agreement, Privacy Policy, or data protection laws
* Claims that authorized App use infringes patents, copyrights, or trademarks

### 13A.2

Conditions include: prompt written notice, provider control of defense/settlement, and client cooperation.

### 13A.3

Exclusions apply for App modifications, software combinations, or out-of-scope use.

## 14. Changes to Terms

### 14.1

Terms may be updated periodically.

### 14.2

Material changes require email notification to the primary Shopify account email.

### 14.3

Material changes receive 30 days' advance notice; minor clarifications may be immediate.

### 14.4

Continued use constitutes acceptance. Disagreement allows termination via uninstallation.

## 15. Governing Law

The Agreement follows United Kingdom law without regard to conflict of law principles.

## 16. Contact

**Email:** [support@discountkit.app](mailto:support@discountkit.app)

**Optizio Ltd**
124 City Road
London
EC1V 2NX
United Kingdom


# POS specific discounts
Source: https://discountkit.app/pos/overview

Use Discount Kit discounts at your physical retail locations

<Frame>
  <img alt="POS only discount image" />
</Frame>

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/sidekick

Create and manage Discount Kit discounts with Shopify's AI assistant

[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

<CardGroup>
  <Card title="Create discounts" icon="wand-magic-sparkles">
    Describe a promotion and Sidekick opens the right Discount Kit builder and
    fills in the settings.
  </Card>

  <Card title="Find discounts" icon="magnifying-glass">
    Ask Sidekick to list or search your existing Discount Kit discounts.
  </Card>

  <Card title="Explain a discount" icon="circle-question">
    Get a plain-language breakdown of what a discount does and when it applies.
  </Card>

  <Card title="Edit discounts" icon="pen-to-square">
    Open an existing discount and ask Sidekick to adjust its settings.
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Open Sidekick">
    Click the Sidekick icon in your Shopify admin to open the chat.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Example prompts

<AccordionGroup>
  <Accordion title="Create a discount" icon="wand-magic-sparkles">
    * "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."
  </Accordion>

  <Accordion title="Find a discount" icon="magnifying-glass">
    * "Show me my active Discount Kit discounts."
    * "Which discounts apply to the Summer collection?"
    * "List my order goal discounts."
  </Accordion>

  <Accordion title="Explain a discount" icon="circle-question">
    * "Explain my 'Spring Sale' discount."
    * "When does my free shipping discount apply?"
  </Accordion>

  <Accordion title="Edit a discount" icon="pen-to-square">
    * "Open my 'BFCM' discount and change the threshold to \$150."
    * "Add an exclusion for the Clearance collection to my order discount."
  </Accordion>
</AccordionGroup>

## 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.
</Note>

<Tip>
  Want to try a discount before it reaches real customers? Combine Sidekick with
  [Test mode](/test-mode) — create the discount with Sidekick, then enable test
  mode so only customers tagged `test` can see it.
</Tip>

## Related

<CardGroup>
  <Card title="Introduction" icon="rocket" href="/documentation">
    New to Discount Kit? Start here.
  </Card>

  <Card title="Custom discounts" icon="sliders" href="/discounts/custom">
    Learn the full custom discount model Sidekick builds on.
  </Card>

  <Card title="Test mode" icon="flask" href="/test-mode">
    Try discounts safely before going live.
  </Card>

  <Card title="Product updates" icon="calendar" href="/changelog">
    See the latest Discount Kit changes.
  </Card>
</CardGroup>


# Test mode
Source: https://discountkit.app/test-mode

Test your discounts before going live — no subscription required

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.
</Note>

## 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](/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](/live/filtering-discounts#filtering-test-mode-discounts) for details.