Tiered discounts

Methods for reading tiered discount incentives for the currently logged-in customer.

These calls hit the Storefront API GET /incentives/tiered_discounts endpoints. The SDK requires a session that includes customerId; otherwise the methods throw with the message Not logged in.

Tiered discount configurations also appear on bundle payloads returned by loadBundleData under incentives. Each tier (Tier) encodes the discount and exactly one eligibility rule: either a minimum quantity (condition_quantity_gte) or a minimum line price (condition_line_price_gte), not both.

listTieredDiscounts v1.81.0 read discounts Types

List tiered discounts with optional filters and cursor pagination.

ESM

import { listTieredDiscounts } from '@rechargeapps/storefront-client';

const result = await listTieredDiscounts(session, {
  status: 'published',
  limit: 25,
});

UMD

const result = await recharge.tieredDiscount.listTieredDiscounts(session, {
  status: 'published',
  limit: 25,
});

Optional query arguments are documented on TieredDiscountsParams.

getTieredDiscount v1.81.0 read discounts Types

Fetch a single tiered discount by numeric or string id.

ESM

import { getTieredDiscount } from '@rechargeapps/storefront-client';

const discount = await getTieredDiscount(session, 123);

UMD

const discount = await recharge.tieredDiscount.getTieredDiscount(session, 123);

id must be non-empty; a blank id throws with the message ID is required.

getTieredDiscountOffers v1.85.0 read discounts Types

Evaluate which tiered discount offers a customer qualifies for given a charge and/or a set of line items. Returns per-offer tier ladders with current-tier tracking and threshold gaps.

At least one of charge_id or line_items must be provided. Works with anonymous sessions (no customerId required).

ESM

import { getTieredDiscountOffers } from '@rechargeapps/storefront-client';

const offers = await getTieredDiscountOffers(session, {
  tiered_discount_context: 'recurring',
  charge_id: 12345,
  line_items: [
    { external_product_id: '99', quantity: 2, total_price: '20.00', purchase_type: 'subscription' },
  ],
  presentment_currency: 'USD',
});

UMD

const offers = await recharge.tieredDiscount.getTieredDiscountOffers(session, {
  tiered_discount_context: 'recurring',
  charge_id: 12345,
  line_items: [
    { external_product_id: '99', quantity: 2, total_price: '20.00', purchase_type: 'subscription' },
  ],
  presentment_currency: 'USD',
});

Request body fields are documented on TieredDiscountOffersRequest. The response shape is TieredDiscountOffersResponse.

Product-of-interest line items

quantity and total_price are optional on each line item and default to 0 and "0.00" respectively. Omitting them turns the entry into a "product of interest" marker: the product still participates in target-match and collection-membership evaluation, but contributes nothing to the customer's current quantity or spend totals. This is useful for surfacing tiered-discount offers for a product the shopper is browsing but has not yet added to a cart or charge — for example, a PDP banner asking "would you like to start qualifying for this discount?".

When combined with charge_id, a product-of-interest marker for a product already on the charge is dropped (the charge wins on collide), so the same call works for both "already on charge" and "not on charge" cases.

const offers = await getTieredDiscountOffers(session, {
  tiered_discount_context: 'recurring',
  charge_id: 12345,
  line_items: [{ external_product_id: '99', purchase_type: 'subscription' }],
});