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.max_reward_percent
Type:number_decimal
The best percentage discount value available for this product/collection.
max_reward_cents
Type:number_integer
The best fixed amount discount in cents. Set to 0 when a percentage discount is available instead.
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.
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_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 |
Threshold Fields
What customers need to buy to qualify.threshold_type
Type:string
How the threshold is measured: QUANTITY, AMOUNT, or NONE
minimum_threshold_value
Type:number
Minimum quantity or amount (in cents) to qualify.
threshold_product_references
Type:list.product_reference
Products that count toward the threshold.
threshold_collection_references
Type:list.collection_reference
Collections that count toward the threshold.
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)
minimum_reward_value
Type:number
Lowest discount value (first tier).
maximum_reward_value
Type:number
Highest discount value (top tier). Most commonly used field!
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.
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.
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.
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).
cart_attribute_key
Type:string
Cart attribute key required for the discount to apply. Empty = no cart attribute requirement.
cart_attribute_value
Type:string
Cart attribute value that must match exactly. Empty = any value is accepted (presence-only check).
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.
reward_values
Type:list.number_integer
Reward values for each tier. Values are:
- percentages when
reward_typeisPERCENTAGE(e.g.,10= 10%) - discount amounts in cents when
reward_typeisFIXED_AMOUNT(e.g.,500= $5 off) - final prices in cents when
reward_typeisFIXED_PRICE(e.g.,1500= $15 final price)
reward_quantities
Type:list.number_integer
For GWP (Gift With Purchase) discounts, the number of free items per tier. Empty for non-GWP discounts.
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.
threshold_messages
Type:list.single_line_text_field
Custom display messages for each tier. Defaults to the discount title if not set.
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.
config
Type:json
Complete discount configuration including tiers and rules. Structure varies by discount type.
TypeScript Type
Next Steps
Code Examples
Practical implementations
Introduction
Learn about Discount Kit Live