Skip to main content

Quick Access Metafields

For simple badge displays, use these scalar metafields instead of parsing the full discount array:
Only one of max_reward_percent or max_reward_cents is set. Percentage discounts are always preferred over fixed amounts.

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. Only set when no percentage discount is available.
{% 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 or FIXED_AMOUNT
{% 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
{% 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.

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 %}

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 (e.g., 10 = 10%) or cents depending on reward_type.
{% assign rewards = discount.reward_values.value %}

{% for reward in rewards %}
  {% if discount.reward_type == 'PERCENTAGE' %}
    <span>{{ reward }}% OFF</span>
  {% else %}
    <span>{{ reward | divided_by: 100.0 | money }} OFF</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

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'
  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[]

  // Targeting
  included_customer_tags: string[]
  excluded_customer_tags: string[]
  included_markets: string[]
  excluded_markets: string[]
  currency: string | null

  // Advanced
  config: Record<string, any>
}

Next Steps