Events

<dkl-tiered-rewards> recomputes its progress on every cart update and emits a single custom event when the cart total crosses a tier boundary. To run your own logic on a tier change, listen for it — see Reacting to changes and the examples on the web component page.

Emits

widgetId

The app block’s id — null on a web component. discountId identifies which tiered rewards discount a concurrent instance tracks.

discount-kit-live:tiered-rewards:tier-change

CustomEvent

Fired when the cart total crosses a tier boundary. The initial render establishes the baseline silently — the event fires only on a subsequent change, in either direction (unlocking a tier, or dropping below one when items are removed). The detail carries resource:

resource: {
  widgetId: string | null
  widgetType: 'tiered-rewards'
  discountId: string
  previousTier: TieredRewardsTier | null
  currentTier: TieredRewardsTier | null
  cartTotalCents: number
}

// previousTier / currentTier are null below the first tier
type TieredRewardsTier = {
  tierLevel: number
  minSpendCents: number // spend in cents, or an item count for a quantity goal
  kind: 'order' | 'shipping' | 'gift'
  discountAmount: number // percent, or CENTS for fixedAmount; 0 for a gift
  discountType: 'percentage' | 'fixedAmount' | ''
  message: string
}

Note currentTier.discountAmount is a percent, or cents in the cart’s currency for fixedAmount. For a goal measured in items, minSpendCents and cartTotalCents are item counts.

A full example payload — the cart crossing from tier 1 into tier 2:

// event.detail.resource on tier-change
{
  widgetId: 'a1b2c3d4',        // the app block's id (null on a web component)
  widgetType: 'tiered-rewards',
  discountId: 'discount-1478638797012',
  previousTier: {
    tierLevel: 1,
    minSpendCents: 5000,
    kind: 'order',
    discountAmount: 10,
    discountType: 'percentage',
    message: 'Save 10%'
  },
  currentTier: {
    tierLevel: 2,
    minSpendCents: 10000,
    kind: 'order',
    discountAmount: 15,        // percent — or CENTS when discountType is 'fixedAmount'
    discountType: 'percentage',
    message: 'Save 15%'
  },
  cartTotalCents: 11000
}

Lifecycle

Each Tiered Rewards instance also emits mount and unmount events as its behaviour attaches and tears down — handy for wiring up (and cleaning up) custom integrations per instance. Both bubble and carry a DklWidgetEventDetail resource. Tiered rewards are order-level, so the payload is just widgetType and widgetId (no product/variant).

discount-kit-live:widget:mount

CustomEvent

Fired once the controller has attached its behaviour to the (already server-rendered) element, after the baseline tier is established. resource: { widgetType, widgetId }.

discount-kit-live:widget:unmount

CustomEvent

Fired when the instance tears down — e.g. the element is removed, or the theme editor re-renders the section. Same resource shape. Use it to detach any listeners or observers you set up on mount.

// event.detail.resource on widget:mount / widget:unmount
{
  widgetType: 'tiered-rewards',
  widgetId: 'a1b2c3d4'         // the app block's id (null on a web component)
}

Next steps

Web ComponentsListener and payload examples for reacting to tier changes.

Tiered Rewards overviewWhat the component does, and how it reads the cart total.