How pricing works
The rule defines adiscountType and discountValue, plus optional selection gates:
A
PERCENTAGE or FIXED_AMOUNT discount applies only when the selection satisfies the configured gates:
- Item count between
minProductCountandmaxProductCount. - Selection value between
minOrderAmountandmaxOrderAmount.
tieredDiscount is a JSON string of tiers. Each tier has discountBasedOn (QUANTITY counts the box’s items, AMOUNT adds up their price), value (the count or amount the tier needs), discountType (PERCENTAGE or FIXED_AMOUNT) and discount.
Appstle’s Function evaluates this and applies the discount automatically once the lines carry the bundle attributes.
Step 1 — Read the rule from the metafield
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 dynamic pricing bundles by bundleType.
Step 2 — Render your selector
Build your own selector and gate the “add to cart” action on the rule:- Allow only eligible variants, and keep each one within its
minQuantityandmaxQuantity. - Track the running item count and subtotal; enable checkout only when both gates are satisfied.
- Show the live discounted total using the preview formula.
Step 3 — Add the bundle to the cart
Add the selected variants with the bundle attributes. For a dynamic pricing bundle,_appstle_bundles_type is CLASSIC_BUILD_A_BOX. You don’t need _appstle_bundle_instance_id: Appstle ignores it on a dynamic pricing box and prices every cart line with the same _appstle-bb-id as one box. Keep one box of a bundle in the cart at a time (see More than one box of the same bundle).
lines for each variant in the box.
Dynamic pricing bundles support subscriptions. If the selection uses a subscription purchase option, pass the chosen
selling_plan on the line (Ajax) or sellingPlanId on the merchandise line (Shopify’s Storefront API), exactly as you would for any subscription line item.More than one box of the same bundle
Appstle ignores_appstle_bundle_instance_id on a dynamic pricing box. Every cart line with the same _appstle-bb-id counts as one box, however many times the shopper added the box. Two boxes of three items count as one box of six:
- With a
maxProductCountof 3, the six items are over the maximum, so neither box gets the discount. - With a
minProductCountof 5, both boxes get the discount, though neither qualifies on its own. - A
FIXED_AMOUNTdiscount applies once for the whole group, not once for each box.
TIERED_DISCOUNT offer also counts the boxes together: every line gets the tier that the combined quantity reaches. On the demo store, an offer with 10% off at 3 items and 15% off at 5 items took 10% off one box of 3 items (56.00 down to 50.40). Two boxes of 3 items in one cart, each with its own _appstle_bundle_instance_id, reached the 5-item tier and got 15% off every line (112.00 down to 95.20), the same as two boxes without an ID. Priced box by box, they would have cost 100.80.
With Validate Discount Quantity on, a tiered offer without minProductCount and maxProductCount takes its limits from its QUANTITY tiers: the lowest tier’s value is the minimum, and the highest tier’s value is the maximum. On the same offer, /cart/add.js answered 422 for the two boxes, with or without instance IDs: “Orders must match the quantity range: Min 3, Max 5”. One box of 3 items was added with its 10% discount.
To price several boxes one by one, use a sectioned bundle instead. It tells boxes apart by _appstle_bundle_instance_id, so each box gets its own discount.
Step 4 — Discount applies automatically
When a box’s lines satisfy the gates, Appstle’s automatic discount applies the percentage or fixed amount in the cart and at checkout. If the box later falls outside a gate (for example, the shopper removes an item), the discount stops applying, and you don’t need to remove it yourself. If the merchant turned on Validate Discount Quantity in the Bundles admin (Settings → Shop Settings), Shopify refuses to add a box outsideminProductCount and maxProductCount, or without one of its mandatory variants. A tiered offer without minProductCount and maxProductCount takes these limits from its lowest and highest QUANTITY tiers (see More than one box of the same bundle). Enforce exact tier quantity at checkout refuses a box outside minProductCount and maxProductCount too. On the Ajax Cart API, POST /cart/add.js then answers HTTP 422, with the merchant’s validation message in message and description. Don’t let your UI build a box like that, and add all of a box’s lines in one request, because a request with only part of a box is refused too.
Only a box’s eligible lines count towards the gates and get the discount. A line is eligible when:
- It carries
_appstle-bb-id. Items the shopper adds outside the box don’t get the box discount and don’t change it. - Its product is in the bundle. The variant is in the rule’s
variants, or, whenproductSelectionTypeisCOLLECTION, the product is in one of the rule’s collections (collectionData). - Its quantity is within the variant’s own limits. When a
variantsentry hasminQuantityormaxQuantity, the variant counts only while its quantity in the box is within them.
isMandatory: true in the rule’s variants. A box without one of them gets no discount, however many other items it has. Add mandatory variants to the box when the shopper opens it, and don’t let the shopper remove them. Appstle’s widget also sends _appstle_bundle_mandatory_products, but you don’t need to.
These are the cases to design for. Each one was run on the demo store’s guest storefront with the Ajax Cart API, against a rule with minProductCount 2, maxProductCount 3, a FIXED_AMOUNT discount of 5.00, one mandatory variant (Colombia Coffee, 20.00), a second variant (Dark Roast Coffee, 18.00) and a third with maxQuantity 1 (Decaf Coffee, 18.00). Unless the row says Validate Discount Quantity is on, the setting was off.
Previewing the discount
Mirror the Function’s math for a live preview (cart prices are the amount times 100 in every currency, such as1800 for $18.00):
This preview is display-only, and it covers
PERCENTAGE and FIXED_AMOUNT rules. The Shopify Function is authoritative at checkout; sourcing the preview from the same discountType / discountValue / gate fields keeps them in sync. For a TIERED_DISCOUNT rule, read the discount from the cart after you add the box (total_discount in /cart.js, or the lines’ discountAllocations in Shopify’s Storefront API).Checklist
1
Bundle shows as Live in the Appstle admin
2
Selection satisfies count and amount gates before checkout
3
Every line carries _appstle-bb-id and _appstle_bundles_type = CLASSIC_BUILD_A_BOX
4
The cart holds at most one box of this bundle
5
Every box holds each variant with isMandatory: true
6
Verify the discounted total in the cart matches your preview
Next steps
Volume discount bundle
Tiered “buy more, save more” discounts.
Fixed pricing bundle
Sell a curated set for one fixed price.