Skip to main content
A volume discount bundle rewards customers for buying more: the discount grows as they cross quantity or spend thresholds. For example, “Buy 3, save 10% · Buy 6, save 20%”. Appstle applies the best matching tier automatically. This guide covers running a volume discount bundle from your own storefront UI. You use the same metafield, cart-line attributes, and Shopify Function that Appstle’s built-in widget uses — only the UI is yours. Read the headless overview first for the automatic-discount model.

How pricing works

The tiers live in the rule’s tieredDiscount field as a JSON-encoded string. Parse it into an array of tier objects: Tier selection — Appstle evaluates every qualifying tier and applies the one that saves the shopper the most:
  1. Keep the line only if the offer’s appliesOn allows its purchase type: SUBSCRIPTION needs a selling plan on the line, and ONE_TIME needs none.
  2. Keep the tiers the line can get: tierPurchaseType works the same way, and a tier with discountAllowedTags needs a signed-in customer with that tag.
  3. Among QUANTITY tiers, keep those whose value is at most the counted quantity. What counts toward a tier says which lines are counted together.
  4. Among AMOUNT tiers, keep those whose value is at most the counted spend: the total price of the same lines.
  5. From all qualifying tiers, apply the one that takes the most off. For a FIXED_BUNDLE_AMOUNT tier, that’s the items’ price minus the tier’s price.

What counts toward a tier

A tier’s quantity or spend is counted over a group of cart lines, and the offer’s discountTargetType sets the group. The merchant picks it under Can shoppers mix items? in the offer’s Products step: No, the same variant only is VARIANT, Yes, variants of one product is PRODUCT, and Yes, any product in this offer is ANY. Two kinds of VARIANT offer count lines together:
  • A Buy X, get Y free offer (bundleSubType BUY_X_GET_Y) counts all its lines together.
  • An offer with Variants shoppers see first set (defaultVariants on the rule, in the Products step under More options) counts the lines of a tier’s preset variants together once the cart holds them all, even when they are different variants.
Lines from three other kinds of bundle never count toward a volume discount tier or get a tier’s discount: lines whose _appstle_bundles_type is CLASSIC_BUILD_A_BOX (a dynamic pricing bundle), SECTIONED_BUNDLE (a sectioned bundle) or BUY_X_GET_Y (a Buy X, get Y bundle). A Buy X, get Y free volume discount is not one of them: its lines carry VOLUME_DISCOUNT. For example, on a VARIANT offer with a 3-item tier, one line of 3 reaches the tier, but two lines of the same variant with 2 and 1 items don’t. On a PRODUCT offer with a 2-item tier, one item each of two variants of the product reaches it. On an ANY offer with a 2-item tier, one item each of two of the offer’s products reaches it.

Step 1 — Read the rule and parse the tiers

Read the active rules from the appstle_bundles.bundle_rules shop metafield — the Shopify-native source, with no call to Appstle’s servers (see Reading bundle configuration). Filter to volume discount bundles by bundleType, then parse the tieredDiscount JSON string.
Fields you need:

Step 2 — Render the tier ladder

Build your own UI from the parsed tiers:
  • Show the ladder (e.g. “Buy 3 → 10% off · Buy 6 → 20% off”) using value, discount, and the labels in the table above. In a market with another currency, convert a FIXED_AMOUNT tier’s discount and an AMOUNT tier’s value first, as Previewing the discount shows.
  • If any tier has a tierPurchaseType or a subscriptionSellingPlan, show the tiers as Step 4 describes.
  • Hide a tier with discountAllowedTags unless the signed-in customer has that tag, and hide a tier with several tags from everyone.
  • Track the running quantity and subtotal of each group of lines that count together (see What counts toward a tier), highlight the tier the customer currently qualifies for, and nudge them toward the next one.

Step 3 — Add to cart

Add the eligible variants with the bundle attributes. For volume discount, _appstle_bundles_type is VOLUME_DISCOUNT.

Discount only items added through the widget (optional)

By default, a line gets its tier discount when its product or variant is in the offer, with or without the attributes above, so an item added with the theme’s own Add to cart button counts too. A merchant can turn on Discount only items added through the widget in the offer’s Discount tiers step, under More options. The setting is applyDiscountOnlyIfAddedFromWidget: a boolean on each rule that Get all bundle rules returns, and a key in the rule’s settings JSON string in the bundle_rules metafield. A missing key means off. With the setting on, only this offer’s uniqueRef qualifies: a line with another offer’s _appstle-bb-id is treated like a line without one. With the setting off, a line with another offer’s _appstle-bb-id gets nothing from a VARIANT offer. On a PRODUCT or ANY offer, and on a Buy X, get Y free offer, it still counts toward the tier and gets the discount. Send the attributes on every line, as above, and your storefront works with either setting.
On a Buy X, get Y free volume discount (bundleSubType BUY_X_GET_Y), a subscription line needs _appstle-bb-id with this setting on or off.

Tier restriction (optional)

When the merchant turns on Keep shoppers on the tier they picked in the offer’s Discount tiers step (tier restriction), the discount is pinned to one explicitly chosen tier rather than auto-selecting the best qualifying one. In that mode, also attach the selected tier’s position:
Only attach _appstle_bundle_combo_id when tier restriction is enabled for the bundle. Without restriction, omit it, and Appstle’s automatic discount applies the best qualifying tier. The pinned tier must match the line’s purchase type: a line without a selling plan pinned to a SUBSCRIPTION tier gets no tier discount.

Free gifts (optional)

A volume discount offer can give free gifts that unlock at a tier. The merchant sets them up under Gifts that unlock as shoppers buy more in the offer’s Discount tiers step. Appstle’s widget adds the unlocked gifts together with the items when the shopper adds a tier to the cart. With your own storefront, add each gift yourself as its own cart line, and Appstle’s automatic discount takes 100% off it. A tier’s own gifts (freeProducts) work differently and aren’t covered here. The rule holds the gifts in two fields, in the bundle_rules metafield and in the Admin API: enableProgressiveGifts (boolean) and progressiveGift, a JSON-encoded string like tieredDiscount. Parse it only when enableProgressiveGifts is true: when it’s false, no gift line is free.
The string also carries the labels and display options the widget uses, such as title, subTitle and hideGiftsUntilUnlocked. The fields that decide the discount: What makes a gift line free:
  • The paid lines reach the tier. The gift is free once the paid lines reach the tier at unlockAtTierIndex or any tier after it, counted the same way as the tier discount. With the gift at index 2 and tiers of 1, 2 and 3 items, 3 items make it free and 2 don’t. A gift at index 0 unlocks with the first tier, even when that tier takes 0% off.
  • The gift is its own cart line, added with the gift’s variantId. Give it the offer’s three attributes from Step 3, as Appstle’s widget does. The discount doesn’t need them on a gift line: a gift without _appstle-bb-id is free too, even when Discount only items added through the widget is on.
  • One unit of each gift variant is free. Add a quantity of 2 and Shopify splits it into a free line of 1 and a paid line of 1.
  • Stamp every gift line progressive_gift. Set _appstle_bundle_combo_id to progressive_gift on each gift line you add. With ONE_GIFT_PER_TIER, a gift line without the stamp is charged. With ALL_SELECTED_VARIANTS, a lone gift line is free with or without it, but when the cart holds a stamped and an unstamped line of the same gift variant, only the stamped one is free. A stamped line also stays out of the tier count and gets no tier discount, which matters when the gift is one of the offer’s own products.
  • A gift stamped for another offer isn’t free. A line stamped progressive_gift with another offer’s _appstle-bb-id gets no discount from this offer. Set the gift line’s _appstle-bb-id to this offer’s uniqueRef, or leave it off.
Read the result from the gift line’s price. In Shopify’s Storefront API, the gift line’s cost.totalAmount is 0.0 and its discountAllocations entry holds the gift’s full price. On a theme, /cart.js shows the gift line’s final_line_price as 0. In this example, the 3 items at 15% off come to 96.90 and the 10.00 gift costs nothing:
The discount never adds or removes a gift line. If the shopper drops below the tier, the gift line stays in the cart at full price, so remove it in your cart code.

Step 4 — Sell tiers on a subscription

A volume discount can mix subscription and one-time tiers, such as a 3-pack on a 90-day plan, a 1-pack on a 30-day plan, and a 2-pack and a 1-pack as one-time purchases. Two tier fields describe them, tierPurchaseType and subscriptionSellingPlan (see How pricing works), and the rule’s appliesOn does the same for the whole offer. The cart line’s selling plan decides which tiers apply. Appstle’s automatic discount gives a SUBSCRIPTION tier only to a line with a selling plan, and a ONE_TIME tier only to a line without one. It checks whether the line has a selling plan, not which plan it is. A tier doesn’t put its selling plan on the line for you: a line you add without one is a one-time purchase, and it can’t get a SUBSCRIPTION tier. Show the tiers the shopper can buy. How depends on the offer’s Use each tier’s own selling plan setting (enableTierSellingPlan in the rule’s settings):
  • On: each tier is a purchase option of its own, so show every tier. A ONE_TIME tier is a one-time purchase. A tier that is SUBSCRIPTION or has a subscriptionSellingPlan is a subscription. Any other tier is a one-time purchase. Appstle’s widget shows no separate subscription choice.
  • Off: let the shopper choose between a subscription and a one-time purchase. Then enable the tiers whose tierPurchaseType is BOTH or matches that choice, and disable the rest. Appstle’s widget keeps the disabled tiers on the page. When the shopper switches, it moves the selection to the tier with the same discountBasedOn and value, if there is one.
Put the selling plan on the line. Add the tier’s line from Step 3 with this selling plan: Take a product’s plans from its selling_plan_allocations, or from selling_plan_groups in /products/<handle>.js. If the rule’s settings has includedSubscriptionPlans or excludeSubscriptionPlans (comma-separated selling plan IDs), offer only the included plans and none of the excluded ones. In the Ajax Cart API, set selling_plan on the item to the plan’s numeric ID. In Shopify’s Storefront API, set sellingPlanId on the cart line to the plan’s global ID, gid://shopify/SellingPlan/<id>. This version of Step 3’s line adds the right plan:
If the plan isn’t attached to the variant, /cart/add.js returns 422:
After a cart change. On a Shopify theme with Use each tier’s own selling plan on, the Appstle Bundles app embed checks the cart after every change. Suppose a line carries a tier’s own selling plan, but its quantity no longer reaches that tier, or the highest tier it now reaches is a higher tier with its own plan. The app embed then moves the line to the highest tier its quantity reaches, skipping SUBSCRIPTION tiers without a plan of their own. Of two tiers with the same value, it takes the one listed first in tieredDiscount. It removes the line and adds it again with that tier’s selling plan, or with none for a one-time tier, so a subscription line can become a one-time purchase. A line with _appstle_bundle_combo_id keeps its tier while its quantity still reaches it, and gets the new tier’s position when it moves. The line then has a new key, so read /cart.js again instead of reusing line keys. Subscription and one-time items in one cart. Some offers let shoppers mix variants of one product or any product in the offer (discountTargetType PRODUCT or ANY, see What counts toward a tier). There, subscription and one-time items count toward one tier together: 2 subscription items and 1 one-time item reach a 3-item BOTH tier. With the offer’s Count subscription and one-time items separately setting on (separateTiersByPurchaseType in the rule’s settings), each purchase type gets the tier its own count reaches.

Step 5 — Discount applies automatically

Appstle’s automatic discount evaluates the qualifying tiers against the cart and applies the best one (or the pinned tier, under restriction) in cart and checkout. As the customer adds or removes quantity, the applied tier updates automatically — no calls from your side.

Previewing the discount

Replicate the best-tier selection for a live preview. Call it once for each group of lines that count together (see What counts toward a tier), with the group’s quantity and subtotal. Prices are the amount times 100 in every currency, such as 1800 for $18.00, as /cart.js returns them. In a market with another currency, convert two of the rule’s numbers first: multiply a FIXED_AMOUNT tier’s discount and an AMOUNT tier’s value by the shopper’s rate, and round to 2 decimals. In a theme, the rate is Shopify.currency.rate. A headless storefront has no Shopify.currency, so there, show the discount from the cart’s discountAllocations instead, which are in the shopper’s currency:
This preview is display-only and covers lines of one purchase type. Appstle’s automatic discount prices the cart and checkout from the same tiers, so check the cart for the discount that applies.

Checklist

1

Bundle shows as Live in the Appstle admin

2

tieredDiscount parsed from its JSON string

3

Every line carries _appstle-bb-id and _appstle_bundles_type = VOLUME_DISCOUNT

4

_appstle_bundle_combo_id attached only when tier restriction is enabled

5

Subscription lines carry a selling plan and one-time lines don't

6

Gift lines carry _appstle_bundle_combo_id = progressive_gift and come out of the cart below their tier

7

Verify the applied tier in the cart matches your preview

Next steps

Fixed pricing bundle

Sell a curated set for one fixed price.

Dynamic pricing bundle

Build-your-own with a percentage or amount discount.