> ## Documentation Index
> Fetch the complete documentation index at: https://discountkit.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Data 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 cols={2}>
  <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>