Skip to main content
A dynamic pricing bundle lets customers build their own selection from an eligible set, and applies a discount to the running total — either a percentage (e.g. “15% off when you bundle any 3”) or a fixed amount (e.g. “$10 off your build-your-own box”). Unlike a fixed pricing bundle, the total scales with what the customer picks; the discount is layered on top. This guide covers running a dynamic pricing 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 rule defines a discountType and discountValue, plus optional selection gates: A PERCENTAGE or FIXED_AMOUNT discount applies only when the selection satisfies the configured gates:
  • Item count between minProductCount and maxProductCount.
  • Selection value between minOrderAmount and maxOrderAmount.
So the customer-facing math is:
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 the appstle_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.
Fields you need:

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 minQuantity and maxQuantity.
  • 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).
On a headless storefront, send one entry in 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 maxProductCount of 3, the six items are over the maximum, so neither box gets the discount.
  • With a minProductCount of 5, both boxes get the discount, though neither qualifies on its own.
  • A FIXED_AMOUNT discount applies once for the whole group, not once for each box.
A 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 outside minProductCount 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, when productSelectionType is COLLECTION, the product is in one of the rule’s collections (collectionData).
  • Its quantity is within the variant’s own limits. When a variants entry has minQuantity or maxQuantity, the variant counts only while its quantity in the box is within them.
A box also needs every mandatory variant. A variant the merchant marked Must be in the box has 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 as 1800 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.