Data reference

Quick Access Metafields

For simple badge displays, use these scalar metafields instead of parsing the full discount array:

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.

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

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

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.

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 ExamplesPractical implementations

IntroductionLearn about Discount Kit Live