Tiered discounts

Methods for reading tiered discount incentives and evaluating which offers apply to a charge, cart, or product.

These calls hit the Storefront API /incentives/tiered_discounts endpoints and need a session with either the read discounts or the read tiered discounts scope. They work for a logged-in customer and for guest sessions without a customerId. Earlier SDK versions required customerId for listTieredDiscounts and getTieredDiscount and threw Not logged in. without one.

Guest sessions

A session created without a logged-in customer (for example loginWithShopifyStorefront with no Shopify customer access token) only gets tiered discount access when the read tiered discounts scope is enabled on your Recharge Storefront Token. Guest sessions never receive read discounts. For guest sessions:

• listTieredDiscounts and getTieredDiscount only return published tiered discounts that are not restricted to customer segments; any other id returns a 404.
• getTieredDiscountOffers must be called with line_items; passing charge_id returns a 422, since there is no customer to check the charge against. Offers from tiered discounts restricted to customer segments are not returned.

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 read tiered 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 read tiered 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 read tiered 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. Guest sessions must use line_items only (see Guest sessions). An offer is returned only while the shopper still has a higher tier to reach.

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' }],
});