Skip to main content

Documentation Index

Fetch the complete documentation index at: https://discountkit.app/llms.txt

Use this file to discover all available pages before exploring further.

Quick Access Metafields

For simple badge displays, use these scalar metafields instead of parsing the full discount array:
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.
These scalar metafields only reflect universal discounts — discounts that apply to all visitors without conditions. The following discount types are excluded from scalar computation:
  • Test mode discounts (test: true)
  • GWP (Gift With Purchase) discounts — 100% off on gifts is misleading as a badge
  • Customer-tagged discounts — only apply to specific customers
  • Market-specific discounts — only apply in certain markets
  • Code-based discounts (method: 'code') — the shopper has to enter the code first
These discounts still appear in the full discounts array where you can filter them in Liquid. Use the scalar metafields for simple, drop-in badges that work for all visitors.

max_reward_percent

Type: number_decimal The best percentage discount value available for this product/collection.
{% 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.
{% 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.
{% 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.
{{ discount.discount_title }}
{%- comment -%} "Buy More Save More" {%- endcomment -%}

discount_type

Type: string The type of discount.
ValueDescription
PRODUCT_VOLUMEVolume/tiered pricing
ORDER_GOALCart-wide order discounts
GWPGift with purchase
BXGYBuy X Get Y (native Shopify)
BASICBasic discount (native Shopify)
FREE_SHIPPINGFree shipping (native Shopify)
SHIPPINGShipping discounts
CUSTOMCustom discount logic
UNKNOWN_APPDiscount from another app
{% 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
{% 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.
{{ discount.minimum_threshold_value }}

threshold_product_references

Type: list.product_reference Products that count toward the threshold.
{% 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.
{% 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)
{% 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!
<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.
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.
{% 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.
{% 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).
{%- comment -%} Tags include 'dk:live' plus anything the merchant added. {%- endcomment -%}
{% if discount.tags contains 'vip' %}
  <span class="vip-only">VIP exclusive</span>
{% endif %}
Every discount surfaced in Discount Kit Live is, by definition, tagged dk:live — so checking for that tag in Liquid is redundant. Use the tags field for additional merchant-defined tags.

Targeting Fields

Who can use it and where it applies.

included_customer_tags

Type: list.single_line_text_field Customer tags that qualify. Empty = all customers.
{% 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.
{% 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.
{% 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).
{% 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.
{% 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).
{% 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.
These fields are arrays where each index corresponds to a tier. For example, thresholds[0] is the first tier’s threshold value.

thresholds

Type: list.number_integer Threshold values for each tier. Values are in cents for amount-based thresholds, or quantity for quantity-based thresholds.
{% 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)
{% 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.
{% 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.
{% 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.
{% 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.
{% 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.
{% if discount.config %}
  {% assign config_data = discount.config.value %}
  {%- comment -%} Use with caution - structure varies {%- endcomment -%}
{% endif %}

TypeScript Type

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

Code Examples

Practical implementations

Introduction

Learn about Discount Kit Live