How pricing works
The tiers live in the rule’stieredDiscount 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:
- Keep the line only if the offer’s
appliesOnallows its purchase type:SUBSCRIPTIONneeds a selling plan on the line, andONE_TIMEneeds none. - Keep the tiers the line can get:
tierPurchaseTypeworks the same way, and a tier withdiscountAllowedTagsneeds a signed-in customer with that tag. - Among
QUANTITYtiers, keep those whosevalueis at most the counted quantity. What counts toward a tier says which lines are counted together. - Among
AMOUNTtiers, keep those whosevalueis at most the counted spend: the total price of the same lines. - From all qualifying tiers, apply the one that takes the most off. For a
FIXED_BUNDLE_AMOUNTtier, 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’sdiscountTargetType 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 (
bundleSubTypeBUY_X_GET_Y) counts all its lines together. - An offer with Variants shoppers see first set (
defaultVariantson 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.
_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 theappstle_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.
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 aFIXED_AMOUNTtier’sdiscountand anAMOUNTtier’svaluefirst, as Previewing the discount shows. - If any tier has a
tierPurchaseTypeor asubscriptionSellingPlan, show the tiers as Step 4 describes. - Hide a tier with
discountAllowedTagsunless 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 isapplyDiscountOnlyIfAddedFromWidget: 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.
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
unlockAtTierIndexor any tier after it, counted the same way as the tier discount. With the gift at index2and tiers of 1, 2 and 3 items, 3 items make it free and 2 don’t. A gift at index0unlocks 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-idis 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_idtoprogressive_gifton each gift line you add. WithONE_GIFT_PER_TIER, a gift line without the stamp is charged. WithALL_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_giftwith another offer’s_appstle-bb-idgets no discount from this offer. Set the gift line’s_appstle-bb-idto this offer’suniqueRef, or leave it off.
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:
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_TIMEtier is a one-time purchase. A tier that isSUBSCRIPTIONor has asubscriptionSellingPlanis 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
tierPurchaseTypeisBOTHor 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 samediscountBasedOnandvalue, if there is one.
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:
/cart/add.js returns 422:
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 as1800 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.